Qolo Developer Quickstart Guide

Overview

This guide walks through creating a person, an account, and a card, then simulating a transaction in the Qolo sandbox.

Before you start

Program GUID: Once you set up a Program on the Qolo platform, Qolo will provide you with your Program GUID, which you'll include in your API requests to specify which Program you're working with.
API Credentials: Along with your Program GUID(s), Qolo will provide you with API keys. These are necessary for authenticating your requests to the Qolo API.

Once you have your Program GUID(s) and API credentials, you're ready to start integrating with Qolo's API. In this guide, you'll learn how to:

Create a Person
Create an Account
Create a Card
Simulate a Transaction

1. Create a Person

To create a new person in the Qolo system, call CreatePerson and provide the person details. See the example request below.

Request

curl -i -X POST \
'https://devapi.qolopay.com/api/{version}/persons' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
  "create_account": true,
  "person_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "mobile_number": "<EXAMPLE_PHONE>",
    "birth_date": "1990-01-01",
    "base_address": {
      "address_line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country": "USA"
    }
  },
  "program_guid": "<PROGRAM_GUID>",
  "account_type": "GENERAL",
  "account_name": "John Doe Account"
}'

Response

Upon success, Qolo returns a 201 status code and details about the created person, including their person_guid, which you'll need for subsequent operations. See the example response below.

{
  "person_details": {
    "identifications": [
      {
        "govt_id_type": "NOTPROVIDED",
        "govt_id_number": "N/A"
      }
    ],
    "person_guid": "<PERSON_GUID>",
    "birth_date": "1990-01-01",
    "email": "john.doe@example.com",
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    // ... other fields ...
  },
  // ... other response data ...
}

2. Create an Account

If you did not create an account as part of the person-creation request, you can create one separately by calling CreateAccount. The previous example sets create_account: true, so avoid creating a duplicate account when following that path.

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": "<WALLET_GUID>",
  "person_guid": "<PERSON_GUID>",
  "account_type": "GENERAL",
  "account_name": "My USD Account"
}'

Response

The response will include details about the created account. Here's a truncated example of what you might receive:

{
  "account_guid": "<ACCOUNT_GUID>",
  "wallet_guid": "<WALLET_GUID>",
  "account_currency": "USD",
  "account_name": "My USD Account",
  "account_type": "GENERAL",
  "available_balance": 0,
  "ledger_balance": 0,
  "suspense_balance": 0,
  "advance_account_details": {
    "account": {
      "account_guid": "<ACCOUNT_GUID>",
      "client_reference_id": "<CLIENT_REFERENCE_ID>",
      "start_date": "2019-08-24T14:15:22Z",
      "limit": 0,
      "outstanding_balance": 0,
      "credit_product": "STANDARD",
      "cycle": "MONTHLY",
      "status": "ACTIVE"
      // ... additional payment_summary and payment_schedule details ...
    }
  },
  "account_status": "SYSTEM",
  "last_txn_guid": "<LAST_TRANSACTION_GUID>",
  "post_date": "2019-08-24T14:15:22Z",
  "mask_account_number": "XXXXXXXX1234",
  "sys_utcinserted": "2019-08-24T14:15:22Z"
  // ... additional status_change_nonmon_detail ...
}

Take note of the account_guid in the response. You'll need this identifier for subsequent operations related to this account, such as creating cards or making transactions.

Key points to note in the response:

account_guid: Unique identifier for the account
wallet_guid: Identifier of the wallet this account belongs to
account_currency: Currency of the account (e.g., "USD")
account_type: Type of the account (e.g., "GENERAL")
available_balance, ledger_balance, suspense_balance: Different balance types for the account
account_status: Current status of the account (e.g., "SYSTEM")
mask_account_number: Masked version of the account number for security

The response also includes additional details about the account, such as advance account details, transaction information, and status change details.

3. Create a Card

To create a new card for a person, call CreateCard and provide the person details.

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": "<PERSON_GUID>",
    "birth_date": "1990-01-01",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "<EXAMPLE_PHONE>",
    "base_address": {
      "city": "Anytown",
      "country": "USA",
      "address_line1": "123 Main St",
      "postal_code": "12345",
      "state": "CA"
    }
  },
  "wallet_guid": "<WALLET_GUID>",
  "program_guid": "<PROGRAM_GUID>"
}'

Response

The response will include details about the created card. Here's a truncated example of what you might receive:

{
  "person": {
    "person_guid": "<PERSON_GUID>",
    "birth_date": "1990-01-01",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "<EXAMPLE_PHONE>",
    "base_address": {
      "city": "Anytown",
      "country": "USA",
      "address_line1": "123 Main St",
      "postal_code": "12345",
      "state": "CA"
    },
    "client_reference_id": "<CLIENT_REFERENCE_ID>"
    // ... other person details ...
  },
  "program_guid": "<PROGRAM_GUID>",
  "card": {
    "card_number": "<CARD_NUMBER>",
    "card_proxy": "<CARD_PROXY>",
    "mask_card_pan": "XXXXXXXXXXXX1234",
    "wallet_guid": "<WALLET_GUID>",
    "issuance_type": "FULL",
    "card_condition": "ORIGINAL",
    "card_status": "PENDING",
    "activation_method": "ONLOAD",
    "expiration_date": "<EXPIRATION_DATE>",
    "person_card_status": "ACTIVE"
    // ... other card details ...
  },
  "fulfillment_data": {}
}

Key points to note in the response:

person: Contains details of the person associated with the card
program_guid: Identifier of the program under which the card was created
card: Contains details of the created card, including:
- card_proxy: A unique identifier for the card, used in place of the actual card number for security reasons
- mask_card_pan: A masked version of the card number
- wallet_guid: Identifier of the wallet this card belongs to
- card_status: Current status of the card (e.g., "PENDING")
- expiration_date: Expiration date of the card in YYMM format
- person_card_status: Status of the card in relation to the person (e.g., "ACTIVE")

Take note of the card_proxy in the response. You'll need this identifier for subsequent operations related to this card, such as simulating transactions.

4. Simulate a Transaction

To simulate a card transaction, call TransactionAuthSimulator.

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": "<CARD_PROXY>",
  "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

The response will include details about the simulated transaction. Here's a truncated example of what you might receive:

{
  "card_proxy": "<CARD_PROXY>",
  "card_auth_txn_guid": "<TRANSACTION_GUID>",
  "request_code": "AUTH",
  "response_code": "APPROVED",
  "reason_code": "00",
  "txn_amount": 10.00,
  "settle_amount": 10.00,
  "billing_amount": 10.00,
  "billing_fee": 0.25,
  "billing_conversion_rate": 1,
  "stan": "123456",
  "settlement_date": "2024-09-10",
  "mcc": "5411",
  "channel_name": "POS",
  "txn_fee_amount": 0.25,
  "settle_fee_amount": 0.25,
  "retrieval_reference": "240910123456",
  "authorization_id_code": "123456",
  "terminal_id": "TERM001",
  "acceptor_id": "MERCH001",
  "acceptor_name_loc": "Test Merchant",
  "txn_currency_code": "USD",
  "settle_currency_code": "USD",
  "billing_currency_code": "USD",
  "avs_indicator": "Y",
  "avs_result": "MATCH",
  "mask_card_pan": "XXXXXXXXXXXX1234",
  "wallet_guid": "<WALLET_GUID>",
  "card_status": "ACTIVE",
  "expiration_date": "<EXPIRATION_DATE>",
  "person_guid": "<PERSON_GUID>",
  "program_guid": "<PROGRAM_GUID>",
  "account_guid": "<ACCOUNT_GUID>",
  "account_currency": "USD",
  "available_balance": 989.75,
  "ledger_balance": 989.75,
  "suspense_balance": 0,
  "account_status": "ACTIVE",
  "request_description": "Purchase transaction",
  "country_code_alpha3": "USA",
  "currency_code_alpha3": "USD",
  "total_fee_amount": 0.25
  // ... additional fields ...
}

Key points to note in the response:

card_auth_txn_guid: Unique identifier for this transaction
response_code and reason_code: Indicate the result of the transaction
txn_amount, settle_amount, billing_amount: Transaction amounts
mcc: Merchant Category Code
channel_name: The channel through which the transaction was made (e.g., "POS")
wallet_guid, person_guid, program_guid, account_guid: Identifiers linking this transaction to various entities
available_balance, ledger_balance: Updated account balances after the transaction
total_fee_amount: Total fees associated with this transaction

This simulated transaction provides a comprehensive view of how a real transaction would be processed and recorded in the Qolo system.

Next Steps

Replace the placeholders with your sandbox values. Confirm the current API version, authentication procedure, wallet provisioning, and sandbox prerequisites with Qolo before trying these examples.