QuickStart Guide: Completing a Transfer

Overview and Purpose:

This guide provides a step-by-step tutorial on making a transfer using the our API. It aims to reduce developer onboarding time, increase ease of API adoption, and ensure developers can implement transfer functionality without needing additional support.

Prerequisites

  • Access to our API. Ensure you have your API key.

  • Familiarity with RESTful APIs and JSON.

Funds Flow in a Transfer

The funds flow involves several key steps and entities.

Here's an overview:

  • Initiation: The transfer process begins when a request is made to move funds from a source account to a destination account. This request includes details such as the amount, currency, and account identifiers.

  • Source Account: The source account, also known as the debited party, is the account from which the funds will be withdrawn. This could be a synthetic account representing a customer's account.

  • Transfer Execution: Once the transfer is initiated, the Newline53 platform processes the request. The platform ensures that the source account has sufficient funds and then moves the specified amount to the destination account.

  • Destination Account: The destination account, or credited party, is the account where the funds will be deposited. This could also be a synthetic account representing another customer's account or an external account.

  • Status Updates: Throughout the transfer process, the status of the transfer is updated. Initially, it may be marked as "queued" or "pending," indicating that the transfer is being processed. Once the transfer is complete, the status will be updated to "completed".

  • Completion: The funds are successfully moved from the source account to the destination account, and both accounts are updated to reflect the new balances.

Steps to Complete a Transfer

Note: Our API calls for transfers have recently changed. The Combined Transfers endpoint now allows clients to create a transfer and counterparty in one API call. This simplifies the process by eliminating the need to first create an external synthetic account and then reference it when initiating a transfer.

Step 1: Set Up Your Environment

Before you start, ensure you have the necessary tools:

  • API Key: Obtain your API key from the Newline53 developer portal.
  • HTTP Client: Use tools like Postman or cURL for testing API endpoints.

For more information on setting up your environment please visit out Postman Collection page.

Step 2: Authenticate

Authenticate your API requests using your API key.

Example (cURL):

curl -X POST "https://sandbox.newline53.com/api/v1/auth/token"
-H "Content-Type: application/json"
-d '{
"apiKey": "YOUR_API_KEY"
}'
For more information, please visit our Auth Reference Page.

Step 3: Identify Source and Destination Accounts

Determine the source (debited party) and destination (credited party) Synthetic Accounts. If you haven't established these accounts, use the POST endpoints to create them.

Example (POST Create a Combined Transfer):

curl --request POST
--url https://sandbox.newline53.com/api/v1/ combined_transfers
--header 'accept: application/json'
--header 'content-type: application/json'
For more information, please visit our Combined Transfers page in our developer documentation.

Step 4: Initiate the Transfer

Once you have the source and destination accounts, initiate the transfer.

Example (Initiating a Combined Transfer):

curl --request POST
--url https://sandbox.newline53.com/api/v1/combined_transfers
--header 'accept: application/json'
--header 'content-type: application/json'

Using the Combined Transfers Endpoint

The Combined Transfers endpoint allows clients to create a transfer and counterparty in one API call. This simplifies the process by eliminating the need to first create an external synthetic account and then reference it when initiating a transfer. For more information, please visit our Transfer’s Guide.

Endpoints:

  • GET List Combined Transfers: GET /combined_transfers
  • POST Create a Combined Transfer: POST /combined_transfers
  • GET Get a Single Combined Transfer: GET /combined_transfers/{uid}

Combined Transfer Entity:

A Combined Transfer is the action of creating both a synthetic account and a transfer in a single API call. This entity includes the following fields:

  • synthetic_account_id
  • synthetic_account_external_uid
  • transfer_id
  • transfer_external_uid
  • status: Queued, Pending, Failed, Completed

POST Create a Combined Transfer

  • Endpoint: POST /combined_transfers
  • Description: Creates a new combined transfer, which includes creating a synthetic account and initiating a transfer in one API call.
  • Example Request:
    {
    "synthetic_account": { "POST /synthetic_accounts request" },
    "transfer": { "POST /transfers request" }
    }

Step 5: Review Transfer Status

After initiating the transfer, check its status to ensure it was successful. You can check the status of your transfer using the get a single combined transfer endpoint, using the MQ, or webhooks.

Example (Get a Single Combined Transfer):

curl -X GET "https://sandbox.newline53.com/api/v1/combined_transfers/TRANSFER_ID" \

-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Transfer Statuses

StatusDescription
queuedTransfers begin in the queued status. queued indicates that Newline has received a valid Transfer request and is preparing the Transfer.
pendingTransfers move from a status of queued to a status of pending. A pending status indicates that Newline has begun the movement of funds to complete the Transfer.
canceledTransfers must be canceled by the originating Customer (or Authorized Representative). Transfers can only enter the canceled state if Newline receives a request while the Transfer is in queued or pending states. A pending state cancellation is not guaranteed as this state also includes payment execution. At that stage, a cancel request will result in an error.
failedThe Transfer has failed. This may occur due to a system error, or problems with the origin and/or destination account. A new Transfer must be created to move the assets.
settledThe Transfer is complete, and the funds have settled in the destination Synthetic account.