XPay APIs

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.

Note
By default, when XPay is enabled, push transactions are turned on and pull transactions are turned off.

Note

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

/XPay/v1/payments

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.

Note

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.

Request attributes

accountNumber

string

Required

Unique identifier for the sender account

senderIdentifier

string

Optional

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

string

Optional

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

string

Required

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

string

Required

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

string

Optional

Extra field for more information. 100 characters maximum.

data

string

Optional

Extra field for more information. 100 characters maximum.

transactionDescription

string

Optional

If left blank, automatically filled in with the account the payment is from and to, and the transaction referenced ID.

255 characters maximum

clientIdentifier

string

Optional

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

string

Required

Dollar amount of transaction in positive integral cents. For example, write $1.00 as 100.

Response attributes

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.

accountNumber

string

Number of the account related to the payment ID

referenceId

string

Unique XPay identifier for the transaction. An internal CR attribute. This ID will always start with X.

status

string

Status of the payment

direction

string

Direction the transaction is moving:

Inbound
Outbound

transactionType

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)

senderIdentifier

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.

senderName

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.

receiverIdentifier

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.

receiverName

string

Defaults to the receiverIdentifier if no name was added to the receiver XPay profile

amount

integer

Dollar amount of transaction in positive integral cents. For example, write $1.00 as 100.

memo

string

Extra field for more information. If empty, does not appear in the response.

data

string

Extra field for more information. If empty, does not appear in the response

transactionDescription

string

Extra field for more information. If not populated, by default says "XPay payment from..." or "XPay payment to..." as appropriate.

clientIdentifier

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.

relatedPaymentId

string

The payment ID received by the party on the other side of the transaction

coreTransactionId

string

Unique CR identifier for the core transaction

productId

string

ID in GUID format of your specific product type on which the account is based. Provided by CR.

partnerID

string

Your ID in the CR system. This ID is in GUID format.

createdAt

string

Date and time the payment was created. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

expiresAt

string

Date and time the payment expired. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

canceledAt

string

Date and time the payment was canceled. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] Null if not relevant.

approvedAt

string

Date and time the payment was approved (pulls only). In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] Null if not relevant.

rejectedAt

string

Date and time the payment was rejected. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm] Null if not relevant.

failedAt

string

Date and time the payment failed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]. Null if not relevant.

completedAt

string

Date and time the payment completed. In this case, the date and time are in this format: yyyy-mm-ddThh:mm:ss[.mmm]

lastModified

string

Internal CR value. Date and time the database entry was last modified.

Copy

Sample request

1
2
3
4
5
6
7
8
9
10
11
12
curl -X GET 
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
https://sandbox.crbcos.com/XPay/v1/payments
{
  "accountNumber": "2207975570",
  "senderName": "John Smith",
  "receiverIdentifier": "2101052583",
  "transactionType": "Push",
  "transactionDescription": "Thank you for the gift",
  "amount": 10000
}

Copy

Response sample

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "b6519877-59f4-4e60-bcfa-afff01184ab2",
  "accountNumber": "2207975570",
  "referenceId": "XP131370YH6Z",
  "status": "Processing",
  "direction": "Outbound",
  "transactionType": "Push",
  "senderIdentifier": "2207975570",
  "senderName": "John Smith",
  "receiverIdentifier": "2101052583",
  "receiverName": "2101052583",
  "amount": 10000,
  "transactionDescription": "Thank you for the gift",
  "relatedPaymentId": "4696135c-55dd-4ca7-9703-afff01184ab2",
  "coreTransactionId": "08261e5b-f1eb-4f83-8e65-afff01184ab2",
  "productId": "cc62e17f-5912-483e-9e42-aed30112fbb6",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "createdAt": "2023-05-11T13:00:30.6690699-04:00",
  "expiresAt": "2023-05-12T13:00:30.6690699-04:00",
  "approvedAt": "2023-05-11T13:00:30.6690699-04:00",
  "lastModifiedAt": "2023-05-11T13:00:30.6690699-04:00"
}

Cancel an XPay payment

/XPay/v1/payments/{id}/cancel

Cancels an outgoing XPay push payment.

Note

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.

Path parameters

string

Required

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.

Copy

Sample request

1
2
3
4
5
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/xpay/v1/payments/1a44a61d-43d2-410d-8a10-afff01191c8c/cancel'

Copy

Response sample

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "id": "1a44a61d-43d2-410d-8a10-afff01191c8c",
  "accountNumber": "2207975570",
  "referenceId": "XP1314GMA923",
  "status": "Canceled",
  "direction": "Outbound",
  "transactionType": "Push",
  "senderIdentifier": "2207975570",
  "senderName": "John Smith",
  "receiverIdentifier": "2128491111",
  "receiverName": "2128491111",
  "amount": 10000,
  "transactionDescription": "Thank you for the gift",
  "relatedPaymentId": "c422f965-d64b-4bcd-b807-afff01191c8c",
  "productId": "cc62e17f-5912-483e-9e42-aed30112fbb6",
  "partnerId": "1e5d3f04-ae24-4af6-9e30-aecf012b99dd",
  "createdAt": "2023-05-11T13:03:29.74-04:00",
  "expiresAt": "2023-05-12T13:03:29.74-04:00",
  "canceledAt": "2023-05-11T13:03:39.3154116-04:00",
  "lastModifiedAt": "2023-05-11T13:03:39.3154116-04:00"
}

Approve an XPay payment

/XPay/v1/payments/{id}/approve

Approves an XPay pull request.

Note

A partner can execute a received XPay pull request only if they have receive pull enabled.

Path parameters

string

Required

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.

Copy

Sample request

1
2
3
4
5
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/xpay/v1/payments/7334b1b0-ebd4-423d-ae4f-afff01194bdb/approve'

Copy

Response sample

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "7334b1b0-ebd4-423d-ae4f-afff01194bdb",
  "accountNumber": "2128491111",
  "referenceId": "XP1313V1CY4T",
  "status": "Processing",
  "direction": "Inbound",
  "transactionType": "Push",
  "senderIdentifier": "2207975570",
  "senderName": "John Smith",
  "receiverIdentifier": "2128491111",
  "receiverName": "2128491111",
  "amount": 10000,
  "transactionDescription": "Thank you for the gift",
  "relatedPaymentId": "1a85ccb4-07e6-4153-9429-afff01194bdb",
  "coreTransactionId": "991df077-cb77-43f9-b769-afff01197c82",
  "productId": "78c80d7b-b65c-4639-99ef-ae5100fca652",
  "partnerId": "50fe4191-b333-4c1a-8cae-ad4401568e22",
  "createdAt": "2023-05-11T13:04:10.113-04:00",
  "expiresAt": "2023-05-12T13:04:10.113-04:00",
  "approvedAt": "2023-05-11T13:04:51.6291145-04:00",
  "lastModifiedAt": "2023-05-11T13:04:51.6291145-04:00"
}

Reject an XPay payment

/XPay/v1/payments/{id}/reject

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.

Path parameters

string

Required

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.

Copy

Sample request

1
2
3
4
5
curl -X POST
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
'https://sandbox.crbcos.com/xpay/v1/payments/e4d838db-073c-4176-a2b9-afff0119a02e/reject'

Copy

Response sample

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "id": "e4d838db-073c-4176-a2b9-afff0119a02e",
  "accountNumber": "2128491111",
  "referenceId": "XP131497DSZM",
  "status": "Rejected",
  "direction": "Inbound",
  "transactionType": "Push",
  "senderIdentifier": "2207975570",
  "senderName": "John Smith",
  "receiverIdentifier": "2128491111",
  "receiverName": "2128491111",
  "amount": 10000,
  "transactionDescription": "Thank you for the gift",
  "relatedPaymentId": "c94bb165-56d3-4de8-8dc4-afff0119a02e",
  "productId": "78c80d7b-b65c-4639-99ef-ae5100fca652",
  "partnerId": "50fe4191-b333-4c1a-8cae-ad4401568e22",
  "createdAt": "2023-05-11T13:05:22.067-04:00",
  "expiresAt": "2023-05-12T13:05:22.067-04:00",
  "rejectedAt": "2023-05-11T13:05:51.7756427-04:00",
  "lastModifiedAt": "2023-05-11T13:05:51.7756427-04:00"
}

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

XPay APIs

Originate an XPay payment

Cancel an XPay payment

Approve an XPay payment

Reject an XPay payment

Associated webhook events

Related topics

Tutorials