Tilt Pay API · Client Pack (IMT)

Use your username and password to obtain an access token, which you need to authenticate your account when using the API.

# cURL
curl -X POST "{baseAuthUrl}/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "{username}",
    "password": "{password}",
    "audience": "{audience}",
    "grant_type": "password",
    "client_id": "{client_id}"
  }'

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 86400
}

List available institutions for a country. Required for account verification and creating transfers.

curl "{baseUrl}/v1/resources/institutions/gh/?list=true" \
  -H "Authorization: Bearer $TOKEN"

{
  "responseCode": 200,
  "responseMessage": "Fetched institutions",
  "data": {
    "gh_tilt": "Tilt Ghana",
    "gh_absa": "Absa Bank Ghana Limited",
    "gh_mtn": "MTN Mobile Money",
    "gh_ecobank": "Ecobank",
    "gh_stanbic": "Stanbic Bank",
    "gh_vodafone": "Vodafone Money",
    "gh_zenith": "Zenith Bank"
    // ... banks, mobile money and savings & loans institutions
  }
}

Fetch the current exchange rate between two currencies.

curl "{baseUrl}/v1/rates/fx/usd/ngn" \
  -H "Authorization: Bearer $TOKEN"

{
  "responseCode": 200,
  "responseMessage": "Fetched currency exchange rate",
  "data": {
    "from": { "currency": "usd" },
    "to": { "currency": "ngn" },
    "rate": 1750.6489495892
  }
}

Gets the real-time balance of an account that the requesting client has permission to view.

curl "{baseUrl}/v1/accounts/{account_institution}/{account_number}/balance" \
  -H "Authorization: Bearer $TOKEN"

{
  "responseCode": 200,
  "responseMessage": "Fetched account balance",
  "data": {
    "balance": 10250.75,
    "currency": "zmw"
  }
}

Retrieve transaction data for an account that the requesting client has permission to view.

curl "{baseUrl}/v1/accounts/{account_institution}/{account_number}/transactions?from_datetime=2024-07-09T00:00:00%2B0000&to_datetime=2024-07-11T00:00:00%2B0000" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Retrieve a list of available statements for an account that the requesting client has permission to view. Statement transaction data is fetched separately from the referenced link — it is not included when listing statements.

curl "{baseUrl}/v1/accounts/{account_institution}/{account_number}/statements" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "statement_id": "stm_01HV...",
      "opening_balance": 9500.00,
      "closing_balance": 10250.75,
      "transactions_count": 42
    }
  ]
}

Retrieve a specific statement. Statement transaction data is included in the response when available, or a link is provided to an archived statement. Transaction data is generally available for 90 days before being archived.

Use the Accept header to specify the response format, such as text/csv.

curl "{baseUrl}/v1/accounts/{account_institution}/{account_number}/statements/{statement_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/csv"

Withdraw funds from your Tilt account to a predefined bank account, registered with Tilt. Supply a unique external_transaction_id (UUID) for idempotency and optional webhook notifications.

curl -X POST "{baseUrl}/v1/accounts/{account_institution}/{account_number}/withdraw" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": {
      "external_transaction_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "amount": 100,
      "narration": "Send to bank",
      "notifications": [
        {
          "on_status": ["ACCEPTED", "SUCCESSFUL", "FAILED"],
          "to_url": "https://example.com/webhooks/tilt"
        }
      ]
    }
  }'

The response includes a transfer_id, the final status, the echoed external_transaction_id, the instruction (debtor/creditor), and an actions array tracing each state change.

Fetch information for an account number if the institution supports account discovery. Use this to verify a recipient before creating a transfer.

curl "{baseUrl}/v1/accounts/zm_airtel/260970000100" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "institution": "zm_airtel",
    "account_number": "260970000100",
    "status": "ACTIVE"
  }
}

Create an IMT transfer (auto-accepting the quote). On creation the transfer status is PENDING; track it via webhooks or by fetching the transfer.

curl -X POST "{baseUrl}/v1/transfers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": {
      "debtor": {
        "institution": "{account_institution}",
        "account_number": "{account_number}",
        "kyc": {
          "first_name": "Roy",
          "last_name": "Milner",
          "id_number": "111111",
          "id_type": "passport",
          "address": "address",
          "country": "us"
        }
      },
      "creditor": {
        "institution": "zm_absa",
        "account_number": "123456",
        "mobile_number": "260960000001",
        "kyc": {
          "first_name": "Tanya",
          "last_name": "Winslow",
          "id_number": "222222222",
          "id_type": "national_id"
        }
      },
      "additional_details": {
        "purpose_of_funds": "GIFT_AND_DONATION",
        "origin_currency": "usd",
        "origin_amount": "50"
      },
      "amount": 1000,
      "currency": "zmw",
      "narration": "test",
      "external_transaction_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "scheme": "imt_transfer",
      "notifications": [
        {
          "on_status": ["ACCEPTED", "QUOTED", "QUOTE_EXPIRED", "PENDING", "PENDING_RETRY",
                        "PENDING_KYC", "KYC_EXPIRED", "SUCCESSFUL", "FAILED"],
          "to_url": "https://example.com/webhooks/tilt"
        }
      ]
    }
  }'

{
  "data": {
    "transfer_id": "trf_01HV...",
    "status": "PENDING",
    "external_transaction_id": "9b1deb4d-...",
    "instruction": { "debtor": { ... }, "creditor": { ... } },
    "actions": [
      { "status": "ACCEPTED", "_meta": { "cause": "...", "trace_api_log_id": "..." } }
    ]
  }
}

Create a quoted transfer without executing it. The request body is identical to POST /v1/transfers. The response returns a transfer_id and quote details — settle it with the endpoint below before the quote expires (QUOTE_EXPIRED).

curl -X POST "{baseUrl}/v1/transfers/quote" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ /* same instruction body as POST /v1/transfers */ }'

Accept and settle a previously quoted transfer, using the transfer_id returned by the quote call.

curl -X PATCH "{baseUrl}/v1/transfers/{transfer_id}/settle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Verify whether a particular external_transaction_id has been received and processed by Tilt. Use this for reconciliation or before retrying after a timeout — it prevents duplicate sends.

curl "{baseUrl}/v1/transfers/verify/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer $TOKEN"

{
  "responseMessage": "A request has been received for this external_transaction_id",
  "data": { "transfer_id": "trf_01HV...", "status": "...", ... }
}

Fetch a transfer using the transfer_id issued by Tilt. The actions array lists every state change; the last action's status matches the transfer's current status.

curl "{baseUrl}/v1/transfers/{transfer_id}" \
  -H "Authorization: Bearer $TOKEN"

Resend the last webhook notification for a transfer — useful when your endpoint was down or you need to replay an event.

curl -X POST "{baseUrl}/v1/transfers/{transfer_id}/resend-notification" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

{
  "data": {
    "webhook": { "request_id": "...", "url": "...", "message": { ... } },
    "response": { "http_code": 200 }
  }
}