Originate a payment
In this tutorial, you'll learn how to:
✅ Originate a push transaction
✅ Originate a pull transaction
✅ Approve a pull transaction
✅ Reject a pull transaction
If you are new to XPay we recommend you read the XPay overview before starting this tutorial.
The tutorial assumes you have a knowledge of APIs and how they work. Refer to the API Overview page for more details.
The tutorial uses these API endpoints:
API | Description |
|---|---|
Originate the transfer (pull or push) | |
Approve the transfer (only for pull payments) | |
Reject the transfer (only for pull payments) |
This tutorial uses these webhooks:
Webhook | Description |
|---|---|
XPay.Payment.Received | Inbound payment request has been received and is awaiting approval |
XPay.Payment.Approved | Payment was approved by the receiver |
XPay.Payment.Rejected | Payment was rejected by the receiver |
XPay.Payment.Completed | Payment has been posted to both the sender's and receiver's accounts |
Make sure you have:
- Partner ID
- XPay push enabled on both partner accounts (enabled by default)
For XPay payments to complete, both the originating and receiving partners must have the appropriate pull or push functionality configured. By default, push payments are turned on and pull payments are turned off.
To receive the webhook events for this tutorial both partner accounts need to register each specific webhook event type. Once you are registered, the event objects are sent to the registered URLs.
The event object contains a list of resource identifiers used to download details on each event.
There are 2 XPay transaction types:
Push transactions - A partner pushes money from their account to another CR partner account
Pull transactions - A partner requests to pull money from the account of another CR partner. The CR partner receiving the pull request must approve or reject the request.
Both push and pull payments transfer funds within our system and funds are immediately accessible.
Call POST /XPay/v1/payments. For this call, some attributes are required. A full list of attributes is found here.
The transactionType attribute must be set to Push.
IMPORTANT We strongly recommend that you include an idempotency key in your request header to provide duplicate protection should the payment fail. Read more about idempotency keys here.
Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.
The CR system receives the request and routes the payment from the sender account to the receiver account.
Approval of push transactions is enabled by default as part of XPay configuration. When enabled, all inbound XPay push transactions approve and post automatically.
The payment posts to the receiver account and the sender account is debited.
By default, XPay is configured to automatically approve push payments. However, if automatic approval is turned off, the sender will have to approve the transaction.
The XPay.Payment.Completed webhook is triggered when the payment is posted to both the sender and receiver accounts.
Call POST /XPay/v1/payments. For this call, some attributes are required. A full list of attributes is found here .
The transactionType attribute must be set to Pull.
The CR system receives the pull request and sends it to the receiver. This triggers the XPay.Payment.Received event on the receiver side. The receiver has the option to approve the request or to reject the request.
To approve the pull request
- Call POST /XPay/v1/payments/{id}/approve. The id variable is the relatedPaymentID in response body of the pull request.
- The XPay.Payment.Approved webhook is triggered.
To reject the pull request
- Call POST /XPay/v1/payments/{id}/reject. The id variable is the relatedPaymentID in response body of the pull request.
- The XPay.Payment.Rejected webhook is triggered
Once the request is approved, the CR system routes the payment from the receiver account to the sender account.
The payment posts to the sender account and the sender account is debited.
The XPay.Payment.Completed webhook is triggered when the payment posts to both accounts.
- If the originating partner doesn’t have XPay enabled the payment will fail. The originating partner receives a synchronous error message.
- If the receiving partner doesn’t have XPay enabled the payment will fail. The originating partner receives an asynchronous error message.
