Tutorials

Originate a pull transaction

8min

How to originate an Account Funding Transaction (AFT)
In this tutorial, you'll learn how to:
✅ Register the relevant webhooks
✅ Sign up a card
✅ Start a pull transaction
This tutorial assumes you have a knowledge of APIs and how they work. Refer to the API overview page﻿  for more details.
An Account Funding Transaction (AFT) lets you pull funds from a debit card for specific purposes. You can use an AFT to fund a wallet or a prepaid card. Or, you can use it to initiate a person to person (P2P) transfer through the card network rails. AFTs are not allowed for buying goods and services.
The tutorial uses these API endpoints:
API
Description
﻿POST /api/Card﻿ 
Signs up a card
﻿POST /api/PullTransaction﻿ 
Starts a pull payment
The tutorial uses these webhooks:
Webhook
Description
CardAuthorized
Reports when a card authorization attempt is completed
Shows you the status of the card
Transaction
Reports a transaction
Before you begin
Make sure you have:
﻿API credentials﻿
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 signed up the card
The dollar amount to send
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.
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"
}
{
   "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"
}
﻿
Start a pull transaction
When you start a transfer, you are requesting funds (as the recipient) from a payor.
Authenticate into the Cross River system. This returns a token to you.
Use the token to call POST /api/PullTransaction.
Cross River sends this request to the card networks. The networks route the transaction to the appropriate bank.
The issuing bank (of the registered debit card) receives the transaction.
The issuing bank either authorizes or declines the transaction.
If the transaction is authorized, Cross River responds to your API call as shown below.
Sample request POST /api/PullTransaction
curl -X POST --header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Bearer 12AAB60C01ED32A0C18D44111A753BF3CE180BC716FEC06D30FC4447C2EAE6B3' -d '{ \ 
   "requestId": "89GVA07C-FJ8X-42NV5-9A00C9-6MS5AQ3D7100", 
   "cardToken":"KR7D47MNJIL2R39OZNRVPC0DIS82ES8JE6J7VU", 
   "amount": 400 
 }
curl -X POST --header 'Content-Type: application/json' 
--header 'Accept: application/json' 
--header 'Authorization: Bearer 12AAB60C01ED32A0C18D44111A753BF3CE180BC716FEC06D30FC4447C2EAE6B3' -d '{ \ 
   "requestId": "89GVA07C-FJ8X-42NV5-9A00C9-6MS5AQ3D7100", 
   "cardToken":"KR7D47MNJIL2R39OZNRVPC0DIS82ES8JE6J7VU", 
   "amount": 400 
 }
﻿
Sample response POST /api/PullTransaction
{
  "version": "1.0.0.0",
  "result": {
    "transactionRequestId": "7CE5A0DC-253B-4AB5-9CC9-6E9BE63D7100",
    "amount": 400,
    "transactionRequestedAt": "2022-08-03T21:09:13.5882004Z",
    "transactionStatus": "Succeeded",
    "errorDescription": null,
    "creditCardId": "KR7D47MNJIL2R39OZNRVPC0DIS82ES8JE6J7VU",
    "railId": "TabaPay",
    "network": "MasterCard",
    "retrievalReferenceId": "8abcb1fa-51f1-4b2d-9998-5948877bdcc0",
    "actualTransactionDoneAt": "2022-08-03T21:09:13.937108Z",
    "requestApproved": true,
    "responseReceived": true,
    "responseCode": "00",
    "responseDescription": "Approved",
    "traceNumber": "xxx",
    "error": null,
    "requesterName": null,
    "requesterMcc": null
  },
  "isSuccessfull": true,
  "isSuccessful": true
}
{
  "version": "1.0.0.0",
  "result": {
    "transactionRequestId": "7CE5A0DC-253B-4AB5-9CC9-6E9BE63D7100",
    "amount": 400,
    "transactionRequestedAt": "2022-08-03T21:09:13.5882004Z",
    "transactionStatus": "Succeeded",
    "errorDescription": null,
    "creditCardId": "KR7D47MNJIL2R39OZNRVPC0DIS82ES8JE6J7VU",
    "railId": "TabaPay",
    "network": "MasterCard",
    "retrievalReferenceId": "8abcb1fa-51f1-4b2d-9998-5948877bdcc0",
    "actualTransactionDoneAt": "2022-08-03T21:09:13.937108Z",
    "requestApproved": true,
    "responseReceived": true,
    "responseCode": "00",
    "responseDescription": "Approved",
    "traceNumber": "xxx",
    "error": null,
    "requesterName": null,
    "requesterMcc": null
  },
  "isSuccessfull": true,
  "isSuccessful": true
}
﻿
﻿

API	Description
POST /api/Card	Signs up a card
POST /api/PullTransaction	Starts a pull payment

Webhook	Description
CardAuthorized	Reports when a card authorization attempt is completed Shows you the status of the card
Transaction	Reports a transaction

🤔

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?

Set up iFrame