XPay

Originate a payment

7min

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

Before you begin

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.

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.

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.

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.

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.

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.

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.

XPay.Payment.Completed Event


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.

XPay pull request example

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

  1. Call POST /XPay/v1/payments/{id}/approve. The id variable is the relatedPaymentID in response body of the pull request.
  2. The XPay.Payment.Approved webhook is triggered.

To reject the pull request

  1. Call POST /XPay/v1/payments/{id}/reject. The id variable is the relatedPaymentID in response body of the pull request.
  2. 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.

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



🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.



Updated 30 Sep 2024
Doc contributor
Doc contributor
Did this page help you?