iWallet API Developer Program
iWallet API is a turnkey solution to make mobile check deposits from mobile devices.
A secure and developer friendly remote check deposit API to process paper checks from mobile phones. The scalable API can also issue refunds, is quick to onboard to have you up and running fast.
- Mobile check deposits
- Integrates with iOS and Android
- Integration with most scheduling apps
- SMS-based touchless signature capture
- Easy accounting/reconciliation via the desktop web-app
- Build individual sub accounts for two or more users
- Built in check fraud protection
Safe. Trusted.
Secure.
- PCI compliant
- 256-bit SSL encryption
- Verisign secured
- Bank-level security and anonymity
- TRUSTe-certified industry leading privacy protection
- Robust tokenization technology keeps sensitive card data out of scope
- Built-in fraud screening tool for a secure protocol when verifying customer identity
iWallet API v1 v1 OAS3
/api-docs/v1/swagger.yaml
API block diagram Show/Hide
Errors
iWallet uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with iWallet servers (these are rare). Some 4xx errors that could be handled programmatically (e.g., a check is declined) include an error code that briefly explains the error reported.
Rate Limits
Users who send many requests in quick succession may see error responses that show up as status code 429. We have several limiters in the API, including:
- A rate limiter that limits the number of requests received by the API within any given second. For most APIs, iWallet allows up to 50 read operations per second and 50 write operations per second in live mode, and 25 operations per second for each in test mode. For the images API, iWallet allows up to 10 read operations per second and 10 write operations per second. Live mode and test mode limits are separate and equal.
- A concurrency limiter that limits the number of requests that are active at any given time. Problems with this limiter are less common compared to the request rate limiter, but it’s more likely to result in resource-intensive, long-lived requests.
Treat these limits as maximums and don’t generate unnecessary load. If you suddenly see a rising number of rate limited requests, please contact support - we may reduce limits to prevent abuse, or increase limits to enable high-traffic applications. To request an increased rate limit, please contact support. If you’re requesting a large increase, contact us 6 weeks in advance of when you’ll need the increased rate limit.
Webhooks
iWallet uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a check payment, a check has rejected, etc
A webhook enables iWallet to push real-time notifications to your app. iWallet uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.
Webhook headers
There are a few HTTP headers that are useful for your application when consuming the webhook request. x-iwallet-topic lets your app know, at a high level, the type of event being sent in the payload. x-request-signature-Sha-256 contains a HMAC SHA256 hash based on the webhook payload and a key which is your webhook secret. The webhook signature should be validated prior to parsing the webhook payload
X-Request-Signature-Sha-256 - ed551cfb4acb48d31e14886bffa33aa417dfa4a3d3778f6141a7f7f92ee64861Event: transaction_state
Sends on each change for transaction state
Response body:
{
event_type: "transaction_state",
event_id: event.id,
transaction: {
"data": {
"id": "BAh7CEkiCGdpZAY6BkVUSSI4Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vOT9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIMZGVmYXVsdAY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--700936561877377e775de9f20570956ef2f34f03",
"type": "transaction",
"attributes": {
"note": null,
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-01-12T11:57:33.104Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": true,
"extra_note": "Est. transfer date: 01/14/22",
"state": "pending_completed",
"auth_code": "33P9N4",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # 4456",
"destination": "Tijuana Friesen"
}
}
}
Servers
Computed URL: https://staging.iwallet.com
Batches
GET /api/v1/public/check21/batches List of batches
Parameters
Name
page integer (query)
Description
Pagination page param
per_page integer (query)
Pagination per page param
Connected-Account-Key* string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"data": [],
"meta": {
"current_page": 1,
"total_pages": 0,
"per_page": 20
}
}
401
Unauthorized
{
"error_messages": [
"Not authorized"
]
}
403
Forbidden
{
"error_messages": [
"Invalid token. Forbidden"
]
}
500
Server error
GET /api/v1/public/check21/batches/{id} Show batch details
Parameters
Name
id* string (path)
Description
batch ID
Connected-Account-Key* string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "successful",
"content": {
"application/json": {
"example": {
"data": {
"id": "2",
"type": "payout_details",
"attributes": {
"show_state": "pending",
"source_on_index": "Check transactions",
"destination_on_index": "Kieth Medhurst",
"show_created_at": "",
"note": null,
"amount": 100
},
"relationships": {
"generic_transactions": {
"data": [
{
"id": "1",
"type": "generic_transaction"
}
]
}
}
},
"included": [
{
"id": "1",
"type": "payout_transactions",
"attributes": {
"type": "Paya::Check21Transaction",
"gid": "BAh7CEkiCGdpZAY6BkVUSSItZ2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vMQY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFRJIh0yMDIyLTA4LTE4VDE0OjQ0OjU5LjAyMVo--99d6a91384ccac3b70d8e746fc68e371de3c1705",
"show_created_at": "Jul 18, 7:44 AM",
"amount": 10,
"gross_amount": 10,
"payment_fee_amount": 0,
"tip_amount": 0
}
}
]
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
500
Server error
PATCH /api/v1/public/check21/finalize/{id} Show Check image
Parameters
Name
id* string (path)
Description
Transaction ID
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "successful",
"content": {
"application/json": {
"example": {
"message": "Transaction successfully processed",
"transaction": {
"data": {
"id": "BAh7CEkiCGdpZAY6BkVUSSI4Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vOT9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIMZGVmYXVsdAY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--700936561877377e775de9f20570956ef2f34f03",
"type": "transaction",
"attributes": {
"note": null,
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-11-07T16:32:34.611Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": true,
"extra_note": "Est. transfer date: 11/09/22",
"state": "pending_completed",
"invoice": null,
"tip_amount": 0,
"final_amount": 10.0,
"auth_code": "4P394E",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # 4456",
"destination": "Reid Dibbert"
}
}
}
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
422
Unprocessable entity
{
"application/json": {
"example": {
"error_messages": [
"ERROR MESSAGE Try again or contact support"
]
}
}
}
500
Server error
Check processing
GET /api/v1/public/check21/images/{id} Show Check image
Parameters
Name
id* string (path)
Description
Transaction ID
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "successful",
"content": {
"application/json": {
"example": {
"front_image": "ZGZnbGtqc2RmZ2wzOThkc2ZqaDMyNDA5OGZzZGtqMzQwMjk4"
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
500
Server error
PATCH /api/v1/public/check21/operations/{id}/void Void check trancation
Parameters
Name
id* string (path)
Description
Transaction ID
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "Successful",
"content": {
"application/json": {
"example": {
"message": "Check successfully voided",
"transaction": {
"data": {
"id": "BAh7CEkiCGdpZAY6BkVUSSIyZ2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVm9pZC8yMD9leHBpcmVzX2luBjsAVEkiDHB1cnBvc2UGOwBUSSIMZGVmYXVsdAY7AFRJIg9leHBpcmVzX2F0BjsAVDA=--fa36eedebb14395b4eef694d580f14b8e7b9d8df",
"type": "transaction",
"attributes": {
"note": "Void reason",
"type": "Paya::Check21Void",
"subtype": null,
"created_at": "2022-11-07T16:32:36.519Z",
"source_phone": null,
"refundable?": false,
"reversable?": false,
"voidable?": false,
"extra_note": null,
"state": "voided",
"invoice": null,
"tip_amount": 0,
"auth_code": "FW4X39",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check",
"destination": "Justin Wiegand"
}
}
}
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
422
Unprocessable entity
{
"application/json": {
"example": {
"error_messages": [
"UNABLE TO VOID TRANSACTION"
]
}
}
}
500
Server error
PATCH /api/v1/public/check21/operations/{id} Request change amount
Parameters
Name
id* string (path)
Description
Transaction ID
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "Successful",
"content": {
"application/json": {
"example": {
"message": "Change amount request successfully created"
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
422
Unprocessable entity
{
"application/json": {
"example": {
"error_messages": [
"Change amount already requested. Please contact support"
]
}
}
}
500
Server error
Activity
POST /api/v1/public/checks21 Create Check21 Transaction
Parameters
No Parameters
Responses
Code
200
Description
Successful
{
"application/json": {
"example": {
"message": "Payment Intent successfully created",
"gid": "BAh7CEkiCGdpZAY6BkVUSSI5Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vMzE_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFQw--9317aa1c222ce9bcde9db9e70c5bc7f32dc27f31"
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
422
Unprocessable entity
{
"application/json": {
"example": {
"error_messages": [
"amount must be greater than 0.5"
]
}
}
}
500
Server error
GET /api/v1/public/transactions List transactions
Parameters
Name
page integer (query)
Description
Pagination page param
per_page integer (query)
Pagination per page param
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "successful",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "BAh7CEkiCGdpZAY6BkVUSSI5Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vMzQ_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFQw--a544b999a2fc2cedf69958e501a48a6d8a24eb4d",
"type": "transaction",
"attributes": {
"note": "test2",
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-07-18T14:45:03.822Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": false,
"extra_note": "Est. transfer date: 07/20/22",
"state": "pending",
"invoice": null,
"tip_amount": 0,
"final_amount": 10.0,
"auth_code": "N3943R",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # ",
"destination": "Marshall Schuster"
}
},
{
"id": "BAh7CEkiCGdpZAY6BkVUSSI5Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vMzM_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFQw--b03cb2deccc9317f805e7c13c14f6cb50b3925ba",
"type": "transaction",
"attributes": {
"note": "test2",
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-07-18T14:45:03.816Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": false,
"extra_note": "Est. transfer date: 07/20/22",
"state": "pending",
"invoice": null,
"tip_amount": 0,
"final_amount": 10.0,
"auth_code": "44MVU9",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # ",
"destination": "Marshall Schuster"
}
},
{
"id": "BAh7CEkiCGdpZAY6BkVUSSI5Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vMzI_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFQw--fb43139564dec4d2e6bc513868cb5d0bcf1f6175",
"type": "transaction",
"attributes": {
"note": "test2",
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-07-18T14:45:03.809Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": false,
"extra_note": "Est. transfer date: 07/20/22",
"state": "pending",
"invoice": null,
"tip_amount": 0,
"final_amount": 10.0,
"auth_code": "R9KCKX",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # ",
"destination": "Marshall Schuster"
}
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"per_page": 20
}
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
500
Server error
GET /api/v1/public/transactions/{id} Show transaction details
Parameters
Name
id* string (path)
Description
Transaction ID
Connected-Account-Key * string (header)
Connected account publishable key
Responses
Code
200
Description
Successful
{
"description": "successful",
"content": {
"application/json": {
"example": {
"data": {
"id": "BAh7CEkiCGdpZAY6BkVUSSI5Z2lkOi8vaXdhbGxldC9QYXlhOjpDaGVjazIxVHJhbnNhY3Rpb24vNDQ_ZXhwaXJlc19pbgY7AFRJIgxwdXJwb3NlBjsAVEkiDGRlZmF1bHQGOwBUSSIPZXhwaXJlc19hdAY7AFQw--9bc033743042c5b410cea6d35060d4a80c1e0828",
"type": "transaction",
"attributes": {
"note": "test2",
"type": "Paya::Check21Transaction",
"subtype": null,
"created_at": "2022-07-18T14:45:04.358Z",
"source_phone": "+12345678901",
"refundable?": false,
"reversable?": false,
"voidable?": false,
"extra_note": "Est. transfer date: 07/20/22",
"state": "pending",
"invoice": null,
"tip_amount": 0,
"final_amount": 10.0,
"auth_code": "T94XKT",
"cashback_pending_notice": null,
"bounce_readable_reason": null,
"amount": 10,
"amount_formatted": "$10.00",
"source": "Check # ",
"destination": "Tristan Ziemann"
}
}
}
}
}
}
401
Unauthorized
{
"application/json": {
"example": {
"error_messages": [
"Not authorized"
]
}
}
}
403
Forbidden
{
"application/json": {
"example": {
"error_messages": [
"Invalid token. Forbidden"
]
}
}
}
404
Not found
{
"application/json": {
"example": {
"error_messages": [
"Not Found"
]
}
}
}
500
Server error