Quickstart

Overview

This guide walks you through your first integration with the Qolo platform by showing you how to create a test transaction in your sandbox environment. By the end, you'll understand the core components needed for payments integration.

Prerequisites

Before starting, ensure you have:

Program GUID: Your unique program identifier for API requests
API Credentials: Authentication keys for accessing the Qolo API
Program Funding Account: A master funding account to load customer accounts
Sandbox Access: Access to Qolo's development environment

What You'll Build

In this guide, you'll:

Create a person (customer) record
Set up an account
Fund the account
Issue a card
Process a test transaction

Step 1: Create a Person

First, create a person record to represent your customer. The request requires:

Government ID information for KYC verification
A unique client reference ID for tracking
Basic personal information
Contact type specification (INDIVIDUAL/CORPORATE)
Address information

Recipe

Use the recipe below for a detailed walkthrough for creating a person.

👩‍👩‍👧

Create a Person

Open Recipe

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/persons' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "person": {
    "identifications": [
      {
        "govt_id_type": "COUNTRYID",
        "govt_id_number": "112223333"
      }
    ],
    "client_reference_id": "12345678-1234-1234-1234-123456789012",
    "birth_date": "1975-02-28",
    "email": "john.smith@qolo.io",
    "first_name": "John",
    "last_name": "Smith",
    "base_address": {
      "address_line1": "222333 PEACHTREE PLACE",
      "address_line2": "",
      "city": "Atlanta",
      "state": "GA",
      "postal_code": "30318",
      "country": "USA"
    },
    "contact_type": "INDIVIDUAL"
  },
  "program_guid": "YOUR_PROGRAM_GUID",
  "fulfillment_data": {
    "issuance_type": "FULL"
  }
}'

Response

A successful request returns a 201 status code and the person details:

{
  "person_details": {
    "person_guid": "2ae6ba4b-f6c0-4817-a158-43e5a87168fd",
    "birth_date": "1990-01-01",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Save the person_guid - you'll need it for subsequent steps.

Step 2: Create an Account

If you didn't set create_account: true in the previous step, create an account separately.

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/accounts' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "account_currencies": ["USD"],
  "wallet_guid": "17eaeda9-c0ab-4ac3-8ef9-27ac9b388a03",
  "person_guid": "2ae6ba4b-f6c0-4817-a158-43e5a87168fd",
  "account_type": "GENERAL",
  "account_name": "My USD Account"
}'

Response

{
  "account_guid": "d2b7c9d2-85e7-4c51-92d0-3f97a47f8d76",
  "wallet_guid": "17eaeda9-c0ab-4ac3-8ef9-27ac9b388a03",
  "account_currency": "USD",
  "account_name": "My USD Account",
  "account_type": "GENERAL",
  "available_balance": 0,
  "ledger_balance": 0,
  "suspense_balance": 0
}

Save the account_guid - you'll need it to fund the account.

Step 3: Fund the Account

Before issuing a card, transfer funds from your program funding account to the customer's account. This step is crucial as cards draw their funds from the associated account.

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/transfers' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "client_reference_id": "12345678-1234-1234-1234-123456789012",
  "transfer_type": "ACCOUNTTOACCOUNT",
  "currency": "USD",
  "amount": 1000.00,
  "description": "Initial account funding",
  "source": {
    "account_guid": "YOUR_PROGRAM_FUNDING_ACCOUNT_GUID"
  },
  "destination": {
    "account_guid": "d2b7c9d2-85e7-4c51-92d0-3f97a47f8d76"
  }
}'

Response

{
  "txn_guid": "abc123def456",
  "amount": 1000.00,
  "currency": "USD",
  "status": "COMPLETE",
  "destination": {
    "account_guid": "d2b7c9d2-85e7-4c51-92d0-3f97a47f8d76",
    "available_balance": 1000.00,
    "ledger_balance": 1000.00
  }
}

Step 4: Issue a Card

Now that the account is funded, create a card linked to the account. The card will draw funds from the account you just funded.

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/cards' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "person": {
    "person_guid": "2ae6ba4b-f6c0-4817-a158-43e5a87168fd"
  },
  "wallet_guid": "17eaeda9-c0ab-4ac3-8ef9-27ac9b388a03",
  "program_guid": "3fa0d2ea-ffcf-485d-94ed-dbf4f861ad2f"
}'

Note: For new persons, include at minimum first_name and last_name instead of person_guid.

Response

{
  "card": {
    "card_proxy": "cproxy0000000000001",
    "mask_card_pan": "534092XXXXXX0007",
    "wallet_guid": "17eaeda9-c0ab-4ac3-8ef9-27ac9b388a03",
    "card_status": "PENDING",
    "expiration_date": "2212"
  }
}

Save the card_proxy - you'll need it to process transactions.

Step 5: Process a Test Transaction

Finally, simulate a card transaction using the funded card.

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/TransactionAuthSimulator' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "auth_request_type": "PURCHASE",
  "card_proxy": "cproxy0000000000001",
  "txn_amount": 10.00,
  "txn_currency_code": "USD",
  "mcc": "5411",
  "channel_name": "POS",
  "terminal_id": "TERM001",
  "acceptor_id": "MERCH001",
  "acceptor_name_loc": "Test Merchant"
}'

Response

{
  "card_proxy": "cproxy0000000000001",
  "card_auth_txn_guid": "f0cb5c93-2e51-4afc-ac13-68fa4ac87119",
  "response_code": "APPROVED",
  "txn_amount": 10.00,
  "available_balance": 989.75,
  "ledger_balance": 989.75
}

Key Transaction Fields:

card_auth_txn_guid: Unique transaction identifier
response_code: Transaction result (APPROVED/DECLINED)
txn_amount: Transaction amount
available_balance: Updated available balance
ledger_balance: Updated ledger balance