Pay By Bank
Use callbacks for Pay By Bank
Use callbacks to get real-time updates from the J.P. Morgan Pay By Bank APIs.
When events occur, Pay by Bank sends them to your callback URL. Your integration can then automatically react to these updates.
The advantages of using callbacks include:
- You don't need to poll the API endpoints for status updates.
- You reduce the load on your server infrastructure.
- You can provide a more proactive user experience because customers do not need to trigger API calls to get updates.
Set the callback URL
Pay By Bank sends notifications to the callback URL you register during onboarding. This is all you need to provide to receive callback updates.
If callback messages to clients are undeliverable due to an issue with your URL, an exponential retry mechanism attempts to re-deliver the callback messages.
Supported events
The Pay By Bank API supports the following types of callbacks:
| Callbacks supported | Description |
|---|---|
| Payments callback | Notifies you about changes in payment statuses such as SENT, FAILED, SETTLED, NONE, and CANCELLED. |
| Payouts callback | Notifies you about changes in payout statuses such as PENDING, COMPLETED, and FAILED. |
Payment statuses and description
| Status | Description |
|---|---|
NONE |
Initial status for a payment. Indicates nothing has happened yet. |
SENT |
Sent the payment. |
SETTLED |
Payment is visible in the recipient's account. |
FAILED |
Payment attempt ended in error. Details are in the statusMessage field. |
CANCELLED |
The payment was unsuccessful due to an unexpected error (for example, a user failed to authorize a payment.) |
Payout statuses and description
| Value | Description |
|---|---|
PENDING |
Default status for a payment. |
COMPLETED |
The payout was successful. |
FAILED |
The payout failed to complete. |
Payments Data Dictionary
The following table captures the data dictionary for the payments message.
| Field name | Mandatory, optional, or conditional | Data type | Description | JSON path | Position | Comments |
|---|---|---|---|---|---|---|
value |
M | String | Represents a monetary amount. The value must be greater than 0.01 and can have up to two decimal places. | $.paymentAmount.value | HTTP Request | |
currency |
M | String | ISO 4217 Alpha-3 currency code. | $.paymentAmount.currency | HTTP Request | |
paymentType |
M | String(ENUM) | Type of payment. | $.paymentType | HTTP Request | |
market |
M | String | ISO 3166-1 alpha-2 country code for the market where the payment is initiated. | $.market | HTTP Request | |
redirectURL |
O | String | Optional redirect URL of the merchant. The end-user is redirected here after successfully authorizing the payment with their bank or financial institution. | $.redirectURL | HTTP Request | |
name |
C | String | Name of the debtor. | $.debtor.name | HTTP Request | Field is CONDITIONAL upon the market |
accountId |
C | String | Debtor account number as identified by the bank or financial institution. | $.debtor.account.accountId | HTTP Request | Field is CONDITIONAL upon the market |
accountIdType |
C | String(ENUM) | Account identifier type. | $.debtor.account.accountIdType | HTTP Request | Field is CONDITIONAL upon the market |
name |
M | String | Name of the creditor. | $.creditor.name | HTTP Request | |
accountId |
M | String | Creditor account number as identified by the bank or financial institution. | $.creditor.account.accountId | HTTP Request | |
accountIdType |
M | String(ENUM) | Account identifier type. | $.creditor.account.accountIdType | HTTP Request | |
reference |
O | String | Free text field to provide a meaningful reference for a payment transaction. | $.reference | HTTP Request | |
id |
M | String | A unique identifier of the payment. | $.id | HTTP Response | |
status |
M | String(ENUM) | Status of the submitted payment request. | $.status | HTTP Response | |
statusUpdatedAt |
M | String(Date) | Last updated date and time of the payment status in ISO 8601 format. | $.statusUpdatedAt | HTTP Response | |
statusMessage |
C | String | Description of the status. | $.statusMessage | HTTP Response | Only applicable when the status is FAILED or LOST |
createdAt |
M | String(Date) | Date and time the payment request was created in ISO 8601 format. | $.createdAt | HTTP Response | |
paymentLinkURL |
M | String | HTTPS URL for making the payment. | $.paymentLinkURL | HTTP Response | |
paymentQRCode |
M | String | HTTPS URL for downloading the QR code image. | $.paymentQRCode | HTTP Response | |
Payouts data dictionary
| Field | Type | Description | Required | Read only |
|---|---|---|---|---|
id |
String | The unique identifier of the payout. | Y | Y |
payoutReference |
String | Reference for the payout. | Y | |
sourcePaymentId |
String | Unique identifier of the source/origin payment transaction | .Y | |
amount |
Object | Object encapsulating currency and value details. | Y | |
└─ currency |
String | The currency in which the payout is being made. | Y | |
└─ value |
Number | The payout amount. | Y | |
payoutType |
String | Type of payout (REFUND, WITHDRAWAL). |
Y | |
status |
Object | Status of the payout. | Y | |
createdAt |
String (Date/Time) | The date and time the payout was initiated. | Y |