Introduction

This guide walks you through managing transfers throughout their lifecycle in the Qolo platform using our REST APIs. You'll learn how to set up the necessary components and execute different types of transfers through practical examples.

Overview

The Transfer API allows you to programmatically move funds between accounts, cards, and external financial instruments in your Qolo implementation. This guide demonstrates key operations by walking through common transfer scenarios:

Creating a Person record for external accounts
Setting up Outside Instruments
Initiating different types of transfers
Managing ACH transfers and cancellations

Prerequisites

Before starting this guide, ensure you have:

A Qolo account with API access
Your API credentials
Basic familiarity with REST APIs
A REST client like Postman or cURL

Authentication

All API requests require authentication using your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Understanding Transfer Types

Before initiating transfers, familiarize yourself with the available transfer types:

Transfer Type	Description	Use Case
`ACCOUNTTOBANK`	Transfer from Qolo account to external bank (ACH Out)	Withdrawing funds to a bank account
`BANKTOACCOUNT`	Transfer from external bank to Qolo account (ACH In)	Depositing funds from a bank account
`CCDCTOACCOUNT`	Transfer from credit/debit card to Qolo account (AFT)	Loading funds from a card
`ACCOUNTTOCCDC`	Transfer from Qolo account to credit/debit card (OCT)	Sending funds to a card

Creating a Person Record

If you're working with external accounts, first create a Person record.

Request

POST https://api.qolopay.com/api/{version}/persons
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "person_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "birth_date": "1990-01-01",
    "base_address": {
      "address_line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country": "USA"
    }
  },
  "create_account": true,
  "program_guid": "your-program-guid"
}

Response

{
  "person_details": {
    "person_guid": "pers-1234-abcd",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "status": "ACTIVE"
  }
}

Take note of the person_guid as you'll need it for subsequent operations.

Adding an Outside Instrument

Next, link an external account or card to your Person record.

Request

POST https://api.qolopay.com/api/{version}/outside_instruments
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "person_guid": "pers-1234-abcd",
  "instrument_country": "USA",
  "instrument_type": "BANKDDA",
  "instrument_settlement_currency": "USD",
  "instrument_category": "INDIVIDUAL",
  "instrument_usage": "PAY-IN-OUT",
  "account_details": {
    "bank_account": {
      "account_type": "CHECKING",
      "account_number": "1234567890",
      "routing_number": "021000021",
      "name_on_account": "John Doe"
    }
  }
}

Response

{
  "outside_instrument_guid": "inst-5678-efgh",
  "status": "ACTIVE",
  "instrument_type": "BANKDDA",
  "mask_account_number": "XXXXX7890"
}

Initiating a Transfer

Now you can create a transfer using your configured accounts.

Request

POST https://api.qolopay.com/api/{version}/transfers
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "client_reference_id": "your-unique-reference",
  "channel_type": "ACH",
  "transfer_type": "BANKTOACCOUNT",
  "amount": "100.00",
  "currency": "USD",
  "description": "Account funding",
  "source": {
    "outside_instrument_guid": "inst-5678-efgh"
  },
  "destination": {
    "account_guid": "acct-9012-wxyz"
  },
  "eft_info": {
    "sec_code": "WEB",
    "identifier_number": "REF123456789",
    "addenda": "Optional additional information"
  }
}

Response

{
  "transfer_guid": "tran-3456-mnop",
  "status": "PENDING",
  "amount": "100.00",
  "currency": "USD",
  "estimated_completion": "2024-02-07T12:00:00Z"
}

Canceling an ACH Transfer

You can cancel an ACH transfer before it's submitted to the bank.

Request

POST https://api.qolopay.com/api/{version}/transfers/eft/cancel
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "txn_guid": "tran-3456-mnop",
  "bank_eft_guid": "eft-7890-qrst"
}

Response

{
  "status": "CANCELLED",
  "cancellation_time": "2024-02-06T14:30:00Z"
}

ACH Processing Times

Standard processing times for ACH transfers:

Submission Time	Same Day ACH	Standard ACH
Before 2:30 PM ET	Available 6:00 PM ET same day	Available noon next business day
After 2:30 PM ET	Available noon next business day	Available noon second business day

Error Handling

The API uses standard HTTP response codes:

200: Success
201: Created
400: Bad Request
401: Unauthorized
403: Forbidden
404: Not Found
429: Too Many Requests
500: Internal Server Error

Example error response:

{
  "error": {
    "code": "INVALID_TRANSFER",
    "message": "Insufficient funds for transfer",
    "details": {
      "available_balance": "50.00",
      "requested_amount": "100.00"
    }
  }
}

Best Practices

Validation
- Always verify account status before initiating transfers
- Validate transfer amounts against available balances
- Check processing windows for ACH transfers
Error Handling
- Implement retry logic for failed transfers
- Monitor transfer status through webhooks
- Store and handle client reference IDs
Security
- Securely store sensitive account information
- Use unique reference IDs for each transaction
- Implement proper authentication for all API calls