Internal Transfers
Internal Transfers
Overview
The Internal Transfer API allows you to transfer funds between two Synctera accounts, in real-time. Common use cases include:
- Moving funds between two accounts owned by the same customer.
- Moving funds between two accounts owned by different customers.
- Moving funds between two internal accounts.
- Between a customer account and an internal account.
This guide will show you how to accomplish a few different use cases using the internal transfers API.
Prerequisites
This guide assumes that you are already familiar with the customer and account creation APIs and have one or more accounts already created and in the appropriate status to be able to move funds.
If not, go through the following guides before continue:
To allow internal transfers between customer accounts, both accounts must be created using an an account template with
is_p2p_enabled
set totrue
.
Internal transfers and transaction types
All transactions in the Synctera platform have both a type
and a subtype
which are used to categorize transactions.
The Internal Transfers API always create a transaction with type internal_transfer
, but allows you to specify the subtype of the transaction via the Internal Transfer type
field in the request payload.
The full set of supported internal transfer types are documented in the Internal Transfer API Reference.
For more details about transaction types, and transactions in general, see the Transaction Guide.
Internal account permissions
It's worth noting that certain internal accounts are special and are reserved exclusively for internal use by the Synctera platform. These are distinguished from normal internal accounts by the is_system_acc
attribute on resource.
When this field is true
, it means that any internal transfers to or from these internal accounts will be declined.
See the Internal Transfers API for more details.
Example: Moving money between accounts
To move funds between two customer accounts:
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H "Content-Type: application/json" \
https://api.synctera.com/v0/transactions/internal_transfer \
--data-binary '
{
"amount": 1025,
"currency": "USD",
"originating_account_id": "35c1a55e-4510-458d-9345-fe08121b5654",
"receiving_account_id": "c8ddc14b-33be-447a-820d-3fe59ad49028",
"type": "ACCOUNT_TO_ACCOUNT"
}'
This will create a transaction that debits of $10.25 from customer account 35c1a55e-4510-458d-9345-fe08121b5654
and credits $10.25 to customer account
c8ddc14b-33be-447a-820d-3fe59ad49028
.
It's also worth highlighting that the amount
in this example in cents, not dollars. The Synctera payment APIs always use the smallest denomination for the given currency.
The response on an successful internal transfer will include the same information in the request payload, with the addition of an id
field that represents the unique transaction id created to represent the transfer:
{
"amount": 1025,
"currency": "USD",
"originating_account_id": "35c1a55e-4510-458d-9345-fe08121b5654",
"receiving_account_id": "c8ddc14b-33be-447a-820d-3fe59ad49028",
"type": "ACCOUNT_TO_ACCOUNT",
"id": "e7ec7e47-0a97-40b8-8477-2fa80ae680f7"
}
You can use the id
with the GET Posted Transaction API API to retrieve additional details about the transaction.
Example: Charging a fee
Charging a fee can be achieved by initiating an internal transfer that debits a customer and credits an internal account that has been allocated for that purpose (for example, a "profits and losses" operating account).
This example will charge a $5.00 account fee against a customer account (0b4e28a7-65fd-4ae0-bbb8-d744ded639a5
), crediting our PnL internal account (a5c2604b-7758-4732-b264-b0ea0a1403d1
):
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H "Content-Type: application/json" \
https://api.synctera.com/v0/transactions/internal_transfer \
--data-binary '
{
"amount": 500,
"currency": "USD",
"originating_account_id": "0b4e28a7-65fd-4ae0-bbb8-d744ded639a5",
"receiving_account_id": "a5c2604b-7758-4732-b264-b0ea0a1403d1",
"type": "FEE"
}'
The main difference between this example and the previous one is:
- We are using a different transaction type (
FEE
) in order to more easily distinguish it from other transactions against the account. originating_account_id
now represents an internal account (fetched from the/v0/internal_accounts
API)
Example: Moving money between internal accounts
Operations teams may need to perform periodic "sweeps" to move funds from one internal account to another as part of regular end-of-day operations.
This example will move $25,000 from an ACH Settlement internal account (0b4e28a7-65fd-4ae0-bbb8-d744ded639a5
), to a Money in and out internal account (3dff4ee6-057a-4b29-bedc-f8de8b838780
):
curl \
-X POST \
-H "Authorization: Bearer $apikey" \
-H "Content-Type: application/json" \
https://api.synctera.com/v0/transactions/internal_transfer \
--data-binary '
{
"amount": 2500000,
"currency": "USD",
"originating_account_id": "0b4e28a7-65fd-4ae0-bbb8-d744ded639a5",
"receiving_account_id": "3dff4ee6-057a-4b29-bedc-f8de8b838780",
"type": "ACH_CREDIT_SWEEP"
}'
Updated over 1 year ago