Bank rails

XPay

10min

﻿
Use XPay to transfer funds directly between 2 different partners inside the Cross River operating system (COS). Because you are transferring funds inside COS, the transfer happens immediately. Funds do not leave the bank with XPay transfers. A transfer can be a push or a pull.
XPay APIs are found in the XPay module of our COS sandbox.
By default, when XPay is enabled, push transactions are turned on and pull transactions are turned off.
﻿Get started﻿ with Cross River APIs
This table presents XPay APIs we describe in detail below.
Action
API Call
Description
﻿Originate an XPay payment﻿ 
POST /XPay/v1/payments
Sends a single XPay payment
﻿Cancel an XPay payment﻿ 
POST /XPay/v1/payments/{id}/cancel
Cancels an outgoing XPay push payment
﻿Approve an XPay payment﻿ 
POST /XPay/v1/payments/{id}/approve
Approves an XPay request for payment (pull request)
﻿Reject an XPay payment﻿ 
POST /XPay/v1/payments/{id}/reject
Rejects an incoming XPay pull payment request.
Originate an XPay payment
Sends a payment from one Cross River partner to another within the CR system.
When you originate an XPay payment, be sure that the receiving account is enabled to accept XPay transfers. For the receiverIdentifier value you usually use the account number of the account you want to send funds to. If the receiving account is set up with the XPay directory, you can use that value for the the receiverIdentifier value. This allows the receiver to keep their account number hidden if they are worried about privacy. Not all accounts have alias values, in which case you'd use the account number only.
The Pull request should look a lot like the Push request, with the main difference being the transaction type. In a Pull request, the receiverIdentifier tells the system which account gets the payment instruction and will be debited if completed. An account must be configured to allow pull transactions to perform a debit. In addition, all debits must be approved by the receiver before the transaction can be completed.
For XPay API calls made by Arix, the fields vary somewhat from those in the sample request below. See the XPay validation guidelines for lending﻿ for more details.
POST
Request
Response
Body Parameters
accountNumber
required
String
Unique identifier for the sender account
senderIdentifier
optional
String
Unique identifier of the XPay participant sending the transfer. This defaults to the account number if the sender did not update their XPay profile with a unique ID such as a phone number.

50 characters maximum.
senderName
optional
String
Name that can be added to identify the account holder. Defaults to the Sender Identifier if the sender did not update their XPay profile with a name.

50 characters maximum.
receiverIdentifier
required
String
Unique identifier of the XPay participant to receive the transfer. This defaults to the account number if the receiver did not update their XPay profile with a unique ID such as a phone number.

50 characters maximum.
transactionType
required
String
Describes the whether the payment is being requested or sent:

- Pull (A credit payment being sent from an sender to a receiver)
- Push (A debit payment being taken from a receiver and given to the originator)
memo
optional
String
Extra field for more information. 100 characters maximum.
data
optional
String
Extra field for more information. 100 characters maximum.
transactionDescription
optional
String
If left blank, automatically filled in with the account the payment is from and to, and the transaction referenced ID.

255 characters maximum
clientIdentifier
optional
String
Use this attribute to add your own unique identifying string to a payment call or COS record. This attribute is useful for idempotency purposes.
amount
required
Integer
Dollar amount of transaction in positive integral cents. For example, write $1.00 as 100.
﻿
Cancel an XPay payment
Cancels an outgoing XPay push payment.
You can only cancel an XPay payment if the receiving partner has automatic pull approval turned off and only as long as the payment hasn’t been approved by that partner.
POST
Request
Path Params
id
required
String
Payment ID. This ID, in GUID format, first appears as the value for this attribute in the response to the originate a payment call.
﻿
Response attributes
The response attributes for this call are the same as for Originate an XPay payment.
Approve an XPay payment
Approves an XPay pull request.
A partner can execute a received XPay pull request only if they have receive pull enabled.
POST
Request
Path Params
id
required
String
Payment ID. This ID, in GUID format, first appears as the value for this attribute in the response to the originate a payment call.
﻿
Response attributes
The response attributes for this call are the same as for Originate an XPay payment.
Reject an XPay payment
Rejects an incoming XPay pull payment request.
The ID in the call is the relatedPaymentID from the response of the original POST call for the pull request.
POST
Request
Path Params
id
required
String
Payment ID. This ID, in GUID format, first appears as the value for this attribute in the response to the originate a payment call.
﻿
Response attributes
The response attributes for this call are the same as for Originate an XPay payment.
Associated webhook events
Event Name
Description
XPay.Payment.Received
Inbound pull payment request has been received and is awaiting approval
XPay.Payment.Canceled
Payment canceled at the sender's request or has expired
XPay.Payment.Approved
Payment was approved by the receiver
XPay.Payment.Rejected
Payment was rejected by the receiver
XPay.Payment.Failed
Payment failed to post to either the sender or receiver's account, most commonly due to insufficient funds
XPay.Payment.Completed
Payment has been posted to both the sender's and receiver's accounts
Related topics
﻿XPay overview﻿ 
﻿Request and response codes﻿ 
﻿Error Codes﻿ 
Tutorials
﻿How to originate an XPay payment﻿ 
﻿How to cancel an XPay payment﻿ 

Action	API Call	Description
Originate an XPay payment	POST /XPay/v1/payments	Sends a single XPay payment
Cancel an XPay payment	POST /XPay/v1/payments/{id}/cancel	Cancels an outgoing XPay push payment
Approve an XPay payment	POST /XPay/v1/payments/{id}/approve	Approves an XPay request for payment (pull request)
Reject an XPay payment	POST /XPay/v1/payments/{id}/reject	Rejects an incoming XPay pull payment request.

Event Name	Description
XPay.Payment.Received	Inbound pull payment request has been received and is awaiting approval
XPay.Payment.Canceled	Payment canceled at the sender's request or has expired
XPay.Payment.Approved	Payment was approved by the receiver
XPay.Payment.Rejected	Payment was rejected by the receiver
XPay.Payment.Failed	Payment failed to post to either the sender or receiver's account, most commonly due to insufficient funds
XPay.Payment.Completed	Payment has been posted to both the sender's and receiver's accounts

🤔

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 15 Oct 2024

Did this page help you?

Error Codes

Request and response codes