Use callbacks for Pay By Bank
Use incoming callbacks to get real-time updates from J.P. Morgan Pay Bank API's.
React to events received on your Pay By Bank callback-url, so your integration can automatically trigger reactions.
The advantages of using callbacks include:
- No need to keep polling the API endpoints for status updates.
- Reduce the overload on server infrastructure.
- Your user experience can be more proactive because customers do not have to trigger API calls to get updates.
Set the callback URL
Pay By Bank sends callback notifications to the callback URL you registered during onboarding process. This is all you need to provide in order to receive callback updates. No additional requests need to be sent to the API.
In the event where callback messages to clients are undeliverable due to an issue with your URL, exponential retry mechanism are in place to re-attempt the delivery of the callback messages.
Supported events
The Pay By Bank API supports two different types of callbacks:
- Payments Callback
- Payouts Callback
| Callbacks Supported | Description |
|---|---|
| Payments Callback | Enables client to get notified about changes in payment statuses such as SENT, FAILED, SETTLED, NONE, and CANCELLED |
| Payouts Callback | Enables client to get notified about changes in payout statuses such as PENDING, COMPLETED and FAILED |
| Status | Description |
|---|---|
| NONE | The initial status for a payment. Indicates nothing has happened yet |
| SENT | Payment has been SENT |
| SETTLED | The Payment was seen on recipient's account |
| FAILED | Attempt ended with error status. The details can be found in statusMessage field |
| CANCELLED | The Payment was unsucessful due to an unexpected error e.g. a user fails to authorize a payment. |
| VALUE | DESCRIPTION |
|---|---|
| PENDING | Default status |
| COMPLETED | Payout was successful |
| FAILED | Payout failed to complete |
Payments Data Dictionary
The below table captures the data dictionary for the payments message.
| Field Name | Mandatory Optional Conditional | Data Type | Description | JSON Path | Position | Comments |
|---|---|---|---|---|---|---|
| value | M | String | The value representation of a monetary amount. The value should be more than 0.01 with maximum of two decimal places allowed. | $.paymentAmount.value | HTTP Request | |
| currency | M | String | ISO 4217 Alpha-3 Currency Code | $.paymentAmount.currency | HTTP Request | |
| paymentType | M | String(ENUM) | The 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 | An optional re-direct URL of the merchant where the end-user will be redirected to once they have successfully authorized 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) | The 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) | The account identifier type | $.creditor.account.accountIdType | HTTP Request | |
| reference | O | String | A free text field that can be used 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) | The status of the submitted payment request | $.status | HTTP Response | |
| statusUpdatedAt | M | String(Date) | The last updated date and time of the payment status in ISO 8601 format | $.statusUpdatedAt | HTTP Response | |
| statusMessage | C | String | A textual description of the status | $.statusMessage | HTTP Response | Only applicable when the status is FAILED or LOST |
| createdAt | M | String(Date) | Indicates when the Payment request was created in the system. Follows ISO date time format | $.createdAt | HTTP Response | |
| paymentLinkURL | M | String | An HTTPS URL to make the payment | $.paymentLinkURL | HTTP Response | |
| paymentQRCode | M | String | An HTTPS URL to download the QR code image to make the payment | $.paymentQRCode | HTTP Response | |
Payouts data dictionary
| Field | Type | Description | Required | ReadOnly |
|---|---|---|---|---|
| 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 |