How to originate an XPay payment

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.

In this tutorial, you'll learn how to

Register the relevant webhooks

Originate a push transaction

Originate a pull transaction

Approve a pull transaction

Reject a pull transaction

The tutorial uses these API endpoints:

API	Description
POST /XPay/v1/payments	Originate the transfer (pull or push)
POST /XPay/v1/payments/{id}/approve	Approve the transfer (only for pull payments)
POST /XPay/v1/payments/{id}/reject	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

Before you begin

Make sure you have:

• API credentials

• Partner ID

• XPay push enabled on both partner accounts (enabled by default)

1. Register the relevant webhook events

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.

2. Originate the XPay transaction

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.

a. To originate a push payment

1. 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.

Note

Money amounts in API calls and responses are written without a decimal point between the dollars and the cents.

2. The CR system receives the request and routes the payment from the sender account to the receiver account.

Note
Approval of push transactions is enabled by default as part of XPay configuration. When enabled, all inbound XPay push transactions approve and post automatically.

3. The payment posts to the receiver account and the sender account is debited.

Note
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.

4. The XPay.Payment.Completed webhook is triggered when the payment is posted to both the sender and receiver accounts.

   Copy

   XPay.Payment.Completed Event

   {
     "id": "00000000-0000-0000-0000-000000000000",
     "eventName": "XPay.Payment.Completed",
     "status": "Pending",
     "partnerId": "00000000-0000-0000-0000-000000000000",
     "createdAt": "2018-07-26T03:48:55.969Z",
     "lastAttemptedAt": "2018-07-26T04:45:15.128Z",
     "resources": [
       "",
     ]
   }

b. To originate a pull payment

1. 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.

   Copy

   XPay pull request example

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   POST /xpay/v1/payments
   {
     "accountNumber": "1234567890",
     "senderName": "John Smith",
     "receiverIdentifier": "9876543210",
     "transactionType": "Pull",
     "memo": "bill pay",
     "data": "INV123",
     "amount": 100
   }

2. 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

3. Once the request is approved, the CR system routes the payment from the receiver account to the sender account.

4. The payment posts to the sender account and the sender account is debited.

5. The XPay.Payment.Completed webhook is triggered when the payment posts to both accounts.