API Reference

GiveCard Transfers: RTP, FedNow, ACH

Send bank transfers over instant payment rails

GiveCard allows you to transfer money directly to individuals bank accounts, with the optional speed of instant payment rails like RTP and FedNow, or the tried and true ACH network as a backup option.

What are RTP and FedNow?

Newer, instant bank transfer rails that allow businesses to deliver funds to recipients in seconds rather than days. ~70% of recipients on the GiveCard Transfers product had bank accounts eligible for instant payments, and adoption by banks is increasing on a daily basis.

Sending a transfer

The process of sending a GiveCard Transfer is quite simple:

  1. Create a recipient, with the createBankTransferRecipientV1 endpoint.
  2. Attach the recipient's bank account via addBankAccountToRecipientV1. We recommend grabbing the bank account details via a service like Plaid, to mitigate typos or invalid accounts.
  3. Send a transfer, via initiateBankAccountTransfersV1 , passing in an amount and a speed. We automatically handle cases where a recipient is ineligible for instant and waterfall down to the next fastest option, sameday ACH, and so we recommend always selecting 'instant' for the speed.

For any subsequent transfers to recipients, you can call getBankTransferRecipientsV1 to get a list of all of your recipients, and then push funds to all of them with initiateBankAccountTransfersV1.

The transfer lifecycle

Unlike with cards, bank transfers have very dubious flows of funds that often make a simple concept quite challenging to predict + manage at scale. We've done our best to simplify this as much as possible.

When you initiate bank transfers with GiveCard, in a successful case we immediately return the associated bank transfer records, and you can use these transferRecord Ids to track the lifecycle of a transfer via getBankTransferV1..

There are 4 different statuses for a bank transfer:

created: This is the status returned when you've just initiated a transfer.

processing: This means that our servers have begun working on the transfer and have put it in a queue to make its way to the different payment networks.

completed: This means that the transfer was sent to the payment networks - note that it does not mean that the transfer has settled with the recipient, simply that it left our bank accounts successfully - unfortunately no network has the capability to indicate the successful delivery of funds, but we've designed a system to reliably estimate it.

failed: This means that the transfer was undeliverable, and the funds have been returned to your funding account. A majority of the time, this is due to invalid bank account details on the recipient.

When has a transfer successfully settled in a recipient's account?

Some of our customers need to know when a transfer has settled in the recipient's account for things like email notifications, internal dashboards or reporting. Given that there is no status that indicates settlement on bank transfer rails, we've designed a system to enable you to reliably estimate it, and we'll handle outlier edge cases. We'll walk through it below:

  1. Initiate a transfer
  2. When the transfer status moves to completed, there will be an estimatedDeliveryDate on it. If we were able to send it via instant rails, then the estimatedDeliveryDate will be the same day as now. If we sent it via ACH, the estimatedDeliveryDate will likely be about 2 business days from now. You can see what rails the transfer was sent on by looking at the transferMethod field on the transfer. Save this estimatedDeliveryDate on your backend, and poll the transaction again on that date.
  3. Call getBankTransferV1 when the estimatedDeliveryDate has arrived - some customers choose to do this as a cron job at the end of each day. If the transfer has the status completed, and the estimatedDeliveryDate has arrived, you can assume that it was a success.

100% of GiveCard instant transfers either settle or fail within just a few minutes, and 99% of GiveCard ACH transfers fail within 48 hours, so our estimatedDeliveryDates are quite reliable to build assumptions off of. Our webhooks can still alert you to failures beyond that 48 hour window in the 1% of edge cases, and we recommend having an operational contingency plan in those cases.

Testing and Simulation in our Sandbox Environment

We've tried to make simulation of this in the sandbox as simple as possible. All transfers have a simulated lifecycle that occurs automatically and will cycle through the expected statuses of the course of a few minutes to allow you to process these realistically!

You can influence the final state of these transfers with the amounts you pass in.

To simulate a successful transfer, pass in an amount of: 1. This transfer will cycle from created to processing to completed over the course a few minutes.

To simulate failed transfers:
For ACHs: set the transferType to sameday_ach and set the amount to 1.02. This transfer will cycle from created to processing to completed to failed over the course of a few minutes.

For instant transfers: set the transferType to instant and set the amount to 1.51. This transfer will cycle from created to processing to completed to failed over the course of a few minutes.

Transfer Cutoff Times

We're happy to help with any and all questions with these, happy transferring!