How to originate a Push to Card transaction
In this tutorial, you'll learn how to
Register the relevant webhooks
Sign up a card
Send a push payment
This 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 |
---|---|
Signs up a card |
|
Sends a payment |
The tutorial uses these webhooks:
Webhook |
Description |
---|---|
|
|
|
Reports a transaction |
Before you begin
Make sure you have:
-
Successfully registered to receive webhook event notifications
-
Signed up the card you are pushing funds to
-
requestId
- your unique reference ID -
cardToken
- the token you received when you registered the card -
The dollar amount to send
-
Enough funds in your account
-
The name of the person or organization originating the push transaction
1. Register the relevant webhook events
Use this endpoint, POST /api/WebhookRegistrations
, to sign up to receive the webhooks available for P2C. These webhooks report relevant events back to your system in real-time. This keeps you up to date on each transaction.
2. Sign up a card
To start a transaction you must first register a card. We use different endpoints to be able to secure your customer's debit card numbers. To register a card, send Cross River the card number. The card number is instantly converted into a token. Cross River doesn't save any card number information. Doing this asynchronously allows Cross River to store your customer's card information. This ensures that you don't need to retrieve the card information again. It also keeps your customer's data secure.
-
Call
POST /api/Card
. -
When a card is registered, Cross River validates the card with the relevant card network. This makes sure the card is a valid card and that it is allowed to receive payments.
-
The
CardAuthorized
webhook is triggered.
Sample request POST /api/Card
{
"RequestId":"49af65c0-f815-4f49-ba8d-b67bf1b125f4",
"FirstName":"Joseph",
"LastName":"Roll",
"OwnerExternalId":"4444",
"Address1":"123 Main Street",
"City":"Venice",
"State":"CA",
"ZipCode":"10989",
"CountryCode":"US",
"PhoneNumber":"5555559275",
"Email":"{youremail}",
"CreditCardNumber":"full card number",
"ExpirationMonth":"06",
"ExpirationYear":"20",
"CCV":"420"
}
3. Start a payment
When you send funds directly to a debit card, we call this a push payment, or a push-to-card (P2C) transaction.
-
Authenticate into the Cross River system. This returns a token to you.
-
Use the token to call
POST /api/transaction
.Cross River makes sure there are funds available in your settlement account to fund the transaction.
-
Cross River sends this request to the card networks. The networks direct the transaction to the right bank.
-
The issuing bank (of the registered debit card) receives the transaction.
-
The issuing bank either authorizes or declines the transaction.
-
If the bank authorizes the transaction, your payee will receive the funds.
Sample request POST /api/transaction
{
"requestId": "{ID}",
"cardToken": "OMOZBSFLNAUG8E2134UDH18WILO2QDA9K6XQVN",
"amount": 100.01,
"sourceSenderName": ""
}
After we receive a successful authorization from the card network, we will respond to your API call. The response looks like this.
Sample response POST /api/transaction
{
"result": {
"transactionRequestId": "e91ea2c5-e8dc-4790-acf7-5dea1cab7216",
"amount": 100,
"transactionRequestedAt": "2019-09-10T00:28:37.76",
"transactionStatus": "Succeeded",
"errorDescription": null,
"creditCardId": "OMOZBSFLNAUG8E2134UDH18WILO2QDA9K6XQVN",
"railId": "RS2",
"network": "visa",
"retrievalReferenceId":
"actualTransactionDoneAt": "2019-09-10T12:28:51",
"paymentSent": true,
"requestApproved": true,
"responseReceived": true,
"responseCode": "00",
"responseDescription": "Approved",
"traceNumber": "000001",
"error": null,
"sourceSenderName": null,
"sourceMcc": 5981,
},
"isSuccessfull": true
}