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 - ed551cfb4acb48d31e14886bffa33aa417dfa4a3d3778f6141a7f7f92ee64861

WEvent: transaction_state

TSends 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"
}
}
}
}

iOS SDK Android SDK Request Sandbox access

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Response

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

Sandbox Sign up

iWallet API Developer Program

Batches

Name

Description

Code

Description

Name

Description

Code

Description

Name

Description

Code

Description

Check processing

Name

Description

Code

Description

Name

Description

Code

Description

Name

Description

Code

Description

Activity

No Parameters

Code

Description

Name

Description

Code

Description

Name

Description

Code

Description