Tilt Pay API · Client Pack (Local)

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. Filter down to a specific institution type with tag or tags.

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

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

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

{
  "responseCode": 200,
  "responseMessage": "Fetched institutions",
  "data": {
    "zw_tilt": "Tilt Zimbabwe",
    "zw_bancabc": "BancABC",
    "zw_cbz": "CBZ Bank",
    "zw_ecocash": "EcoCash",
    "zw_onemoney": "OneMoney"
    // ... banks and mobile money institutions
  }
}

Fetch the details of a single institution by its identifier.

curl "{baseUrl}/v1/resources/institutions/zw_bancabc" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": "zw_bancabc",
    "name": "BancABC",
    "country": "zw",
    "tags": ["bank"]
  }
}

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": "zwl"
  }
}

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=2022-05-30T14:50:00%2B0000&to_datetime=2022-06-01T00: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/zw_bancabc/123456789" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "institution": "zw_bancabc",
    "account_number": "123456789",
    "status": "ACTIVE"
  }
}

Create a local transfer. 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}"
      },
      "creditor": {
        "institution": "zw_bancabc",
        "account_number": "123456789"
      },
      "amount": 10,
      "currency": "{currency}",
      "narration": "test",
      "external_transaction_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "scheme": "local_transfer",
      "notifications": [
        {
          "on_status": ["ACCEPTED", "PENDING", "PENDING_RETRY", "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": "..." } }
    ]
  }
}

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 }
  }
}