API Documentation

Appearance

Direct Carrier Billing (DCB) ​

Use this page to create payments via mobile carrier billing using the common Payment API endpoint. Authentication and base URL follow the Payment API docs.

  • Base URL: https://api.paylander.com/api/v1/payment/
  • Endpoint: POST /v1/payment/

Integration Models ​

DCB supports two integration models:

  • Redirect flow: Only the type parameter is submitted. The customer is redirected to our secure hosted page to enter their card details.
  • Server-to-Server: You collect/handle user details; send full data in payment_method.

Redirect Flow ​

Use when subscriber interaction happens in our hosted frontend. Your backend only specifies the payment method type.

Common fields (see Payment API):

  • channel (UUID, required)
  • amount (object, required)
    • currency (ISO 4217, required)
    • value (string, required)
  • external_id (string, optional)
  • return_url (string, recommended)
  • payment_method (object, required)

payment_method (type: dcb) ​

Required:

  • type → "dcb"
  • user_id → Your internal user identifier

Example Request (Hosted) ​

json
{
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "amount": { 
    "currency": "KZT", 
    "value": "1101.00" 
  },
  "payment_method": { 
    "type": "dcb", 
    "user_id": "9c3a5a77-3b6c-4b87-b746-2c57f1a19d29" 
  },
  "return_url": "https://your-company.com/success",
  "callback_url": "https://your-company.com/callback",
  "external_id": "YOUR_ORDER_NUMBER"
}

Example Response (Hosted) ​

json
{
  "status": "processing",
  "transaction_id": "b7c3f1e4-5a2d-4f8c-9d1b-2a3f7e9c6d10",
  "amount": { 
    "currency": "KZT", 
    "value": "1101.00" 
  },
  "redirect_url": "https://pay.paylander.com/dcb/b7c3f1e4-5a2d-4f8c-9d1b-2a3f7e9c6d10/",
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "payment_method": {
    "type": "dcb",
    "user_id": "9c3a5a77-3b6c-4b87-b746-2c57f1a19d29"
  },
  "create_date": "2025-10-15T12:05:00.000000+00:00"
}

Notes:

  • For Hosted, subscriber completes any OTP/consent within the hosted flow. Use redirect_url when provided.

Server-to-Server ​

Use when your backend collects subscriber details directly.

Common fields (see Payment API):

  • channel (UUID, required)
  • amount (object, required)
    • currency (ISO 4217, required)
    • value (string, required)
  • external_id (string, optional)
  • return_url (string, recommended)
  • payment_method (object, required)

payment_method (type: dcb) ​

Supported fields for Server-to-Server:

  • type → "dcb"
  • user_id → Your internal user identifier
  • phone → Subscriber phone number
  • first_name → Subscriber first name
  • last_name → Subscriber last name

Example Request (Server-to-Server) ​

json
{
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "amount": {
    "currency": "KZT",
    "value": "111.00"
  },
  "payment_method": {
    "type": "dcb",
    "user_id": "9c3a5a77-3b6c-4b87-b746-2c57f1a19d29",
    "first_name": "Daniyar",
    "last_name": "Akhmetov",
    "phone": "77015551234"
  },
  "return_url": "https://your-company.com/success",
  "callback_url": "https://your-company.com/callback",
  "external_id": "YOUR_ORDER_NUMBER"
}

Example Response (Server-to-Server) ​

json
{
  "status": "processing",
  "transaction_id": "e2b1a0d3-9c4f-4b2d-8a73-7fd79f70f4a1",
  "amount": { 
    "currency": "KZT", 
    "value": "111.00"
  },
  "redirect_url": "https://pay.paylander.com/dcb/e2b1a0d3-9c4f-4b2d-8a73-7fd79f70f4a1/",
  "channel": "8fec39b6-c41b-46d6-b219-61d115fdfa2d",
  "payment_method": {
    "type": "dcb",
    "user_id": "9c3a5a77-3b6c-4b87-b746-2c57f1a19d29",
    "first_name": "Daniyar",
    "last_name": "Akhmetov",
    "phone": "77015551234"
  },
  "create_date": "2025-10-15T12:00:00.000000+00:00"
}

Confirm Flow (Server to Server) ​

When payment_method.state is waiting_for_code, the client must call the confirm endpoint (/v1/payment/confirm/).

Confirm request body:

json
{
  "id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "code": "123456"
}

Possible outcomes:

  • Waiting for provider approval: response remains processing and payment_method.state becomes waiting_for_provider.

Example (abbreviated, structure same as processing response):

json
{
  "status": "processing",
  "transaction_id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "payment_method": {
    "type": "dcb",
    "phone": "919812345678",
    "state": "waiting_for_provider"
  }
}
  • Confirmed: response returns completed without the payment_method object.
json
{
  "status": "completed",
  "transaction_id": "58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8",
  "amount": {
    "currency": "KZT",
    "value": "111.00"
  },
  "redirect_url": "https://pay.paylander.com/dcb/58d3f0a2-4c84-40d9-9ebe-e3b1137a49c8/",
  "create_date": "2025-10-15T11:19:17.254731+00:00"
}

Notes for Server to Server:

  • The state field appears only in Server to Server responses and indicates next steps.
  • waiting_for_code → collect verification_code from the payer and call /v1/payment/confirm/.
  • waiting_for_provider → approval pending.

© 2025 Paylander