API Documentation

Get your API credentials

Create a developer account to generate your access tokens.

Ready to start?

To use the Dialo API, first create a developer account, then get your authentication credentials.

Create your account on the developer portal
Confirm your email and complete your profile
Generate your credentials (client_id and client_secret) in the API section
Call the authentication endpoint to get your Bearer token

Create my developer account Free · account active within minutes

Important information

Your credentials are confidential: never share them
Tokens are valid for 1 hour
Test in the sandbox environment first
Read our security guide for best practices

POST

Authentication

Get an access token to authorise your API requests.

https://auth.dialo-pay.com/auth/realms/m360/protocol/openid-connect/token

Generate a Bearer token to authorise API requests. The token is valid for 1 hour and must be sent in the Authorization header of every request.

Create your credentials (client_id and client_secret) on the developer portal.

Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Your application's client ID
client_secret	string	Yes	Your application's client secret
grant_type	string	Yes	Fixed value `client_credentials`

Example request

Terminal

curl -X POST "https://auth.dialo-pay.com/auth/realms/m360/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=VOTRE_CLIENT_ID" \
  -d "client_secret=VOTRE_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Example response

JSON response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhZ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "profile email"
}

POST

Initiate a payment

Creates a transaction and returns a hosted payment URL.

https://api.dialo-pay.com/pay/v1/init-payment

Creates a transaction and returns a hosted payment URL where the customer completes the payment.

Parameters

Parameter	Type	Required	Description
amount	integer	Yes	Amount in the smallest unit (e.g. cents)
currency	string	Yes	Currency code (XOF, USD…)
callbackUrl	string	Yes	Payment notification URL
reference	string	No	Unique reference for your transaction

Example request

Terminal

curl -X POST "https://api.dialo-pay.com/pay/v1/init-payment" \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "XOF",
    "callbackUrl": "https://votre-site.com/webhook",
    "reference": "ORDER-12345"
  }'

Example response

JSON response

{
  "transactionId": "txn_5f7e8d9a0b1c2d3e",
  "paymentUrl": "https://pay.dialo-pay.com/checkout/txn_5f7e8d9a0b1c2d3e",
  "reference": "ORDER-12345",
  "amount": 1000,
  "currency": "XOF",
  "status": "PENDING"
}

POST

Direct payments

Make a direct payment by bank card or Mobile Money.

https://api.dialo-pay.com/pay/v1/direct-pay?type={type}

Makes a direct payment without redirection. Supports bank cards and mobile payments (Wave, Orange Money, etc.).

Query parameters

Parameter	Type	Required	Description
type	string	Yes	Payment type: `card`, `wave`, `orange`, `mtn`

Body parameters

Parameter	Type	Required	Description
transactionReference	string	Yes	Reference of the initial transaction
card	object	Conditional	Card details (for `type=card`)
mobile	object	Conditional	Mobile details (for `type=wave`, `orange`, `mtn`)

Example request — bank card

Terminal

curl -X POST "https://api.dialo-pay.com/pay/v1/direct-pay?type=card" \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 65c34e5c-e31b-48c4-aebc-cbfd65505918" \
  -d '{
    "transactionReference": "cb84c253-66d0-4619-91c8-2e3e056432b6",
    "card": {
      "cardNumber": "5531 8866 5214 2950",
      "expiry": "06/26",
      "cvv": "123",
      "cardHolderName": "test"
    }
  }'

Example request — Mobile Money (Wave)

Terminal

curl -X POST "https://api.dialo-pay.com/pay/v1/direct-pay?type=wave" \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 65c34e5c-e31b-48c4-aebc-cbfd65505918" \
  -d '{
    "transactionReference": "cb84c253-66d0-4619-91c8-2e3e056432b6",
    "mobile": {
      "countryCode": "225",
      "proxy": "wave",
      "phoneNumber": "0707144799"
    }
  }'

Example response

JSON response

{
  "transactionReference": "7de13c1a-9aaf-464a-939c-927b6bfb140c",
  "pspTransactionId": "chg_FEIGfNVr1J",
  "status": "succeeded",
  "amount": 100.0,
  "currency": "XOF",
  "message": "Hosted Link"
}

POST

Payment authorisation

Authorise a payment with a PIN code and OTP.

https://api.dialo-pay.com/pay/v1/authorize-pay

Authorises a payment that needs extra validation (PIN code, OTP).

Parameters

Parameter	Type	Required	Description
transactionReference	string	Yes	Transaction reference
chargeId	string	Yes	PSP charge ID
codePin	string	Conditional	PIN code (if required)
codeOtp	string	Conditional	OTP code (if required)

Example request

Terminal

curl -X POST "https://api.dialo-pay.com/pay/v1/authorize-pay" \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: 65c34e5c-e31b-48c4-aebc-cbfd65505918" \
  -d '{
    "transactionReference": "609dc461-d02f-42e4-8d97-4e5740462fc0",
    "chargeId": "chg_75yI73LrUr",
    "codePin": "1234",
    "codeOtp": ""
  }'

Example response

JSON response

{
  "transactionReference": "cb260447-1704-4f98-af42-716ddc20d05e",
  "pspTransactionId": "chg_E8zRWdVKaY",
  "status": "succeeded",
  "amount": 100.0,
  "currency": "XOF",
  "message": "Hosted Link",
  "qrCode": null,
  "link": null
}

GET

Transaction status

Returns the full details of a transaction.

https://api.dialo-pay.com/pay/v1/transactions/{transactionReference}

Returns the full details of a transaction, including its status, amount, currency and payment processor information.

Example request

Terminal

curl -X GET "https://api.dialo-pay.com/pay/v1/transactions/5fa7fc82-e049-4b3d-adad-8c934ddfcc66" \
  -H "Authorization: Bearer VOTRE_JETON" \
  -H "X-Correlation-Id: 65c34e5c-e31b-48c4-aebc-cbfd65505918"

Example response

JSON response

{
  "id": "2692f2f2-3f60-438e-9b17-cffec1b6d82a",
  "transactionReference": "5fa7fc82-e049-4b3d-adad-8c934ddfcc66",
  "pspTransactionId": "cee25042-3147-4a7f-a8f2-e981673abd6e",
  "status": "canceled",
  "targetId": "a8115f49-4be9-443b-ac0a-ef5ecd83f08f",
  "targetType": "order",
  "amount": 5000,
  "currency": "XOF",
  "gateway": "card",
  "payType": "DEBIT",
  "createdAt": "2025-07-09T22:37:01.465383"
}

Possible statuses

Status	Description
created	Transaction created
pending	Awaiting processing
succeeded	Payment succeeded
failed	Payment failed
canceled	Transaction cancelled

HTTP response codes

HTTP status codes used by the API.

Code	Description
200 OK	Request processed successfully
201 Created	Resource created successfully
400 Bad Request	Malformed request or invalid parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Access denied
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Internal server error

Get your API credentials

Authentication

Parameters

Example request

Example response

Initiate a payment

Parameters

Example request

Example response

Direct payments

Query parameters

Body parameters

Example request — bank card

Example request — Mobile Money (Wave)

Example response

Payment authorisation

Parameters

Example request

Example response

Transaction status

Example request

Example response

Possible statuses

HTTP response codes