Quickstart

This guide takes you from creating an application in SoleasPay to tracking your first transaction.

Mysoleas Identity Cloud manages authentication and users for your applications. It does not replace the application created in SoleasPay that provides API credentials for the gateway.

1. Prepare your domains

All protected business requests go through the gateway.

https://api.mysoleas.com

User OAuth2/OIDC journeys go through Mysoleas Identity Cloud.

https://account.mysoleas.com

Store these URLs in environment variables. This makes tests, workers, and back-office tools easier to maintain.

2. Create an application in SoleasPay

Before calling gateway endpoints, create an application in SoleasPay from your merchant area. This application represents your API integration. Keep the two generated credentials:

Credential	Role
`sp_client_id`	Identifies the application created in SoleasPay
`sp_client_secret`	Server-side secret used to get a gateway token

Never put sp_client_secret in a frontend, mobile application, or public repository. It must stay on the backend.

3. Get a gateway token

Use the credentials of the application created in SoleasPay.

curl -X POST "https://account.mysoleas.com/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "sp_client_id": "YOUR_SOLEASEPAY_APP_CLIENT_ID",
    "sp_client_secret": "YOUR_SOLEASEPAY_APP_CLIENT_SECRET"
  }'

The response contains an access_token. This token represents the application created in SoleasPay and is sent to the gateway.

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "token_expired_at": 1785259148
}

The token obtained here is for API gateway calls. The user JWT from Sign in with Mysoleas is used to open a user session in your own application.

4. Call the gateway

Send the token in x-sp-auth-token.

curl "https://api.mysoleas.com/service/list?country=CMR&currency=XAF" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

You can also send context headers when your application manages several environments or countries.

Header	Usage
`x-sp-auth-token`	Required Bearer token obtained from an application created in SoleasPay
`X-Request-Id`	Merchant-side trace identifier
`X-Idempotency-Key`	Explicit idempotency key for sensitive operations
`X-SP-Country`	Active country, for example `CMR`
`X-SP-Environment`	Logical environment, for example `prod` or `dev`

5. Choose a service

List available services before you create a transaction. The service code becomes the provider value in payment payloads.

curl "https://api.mysoleas.com/service/list?country=CMR&currency=XAF" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN"

A service that can be used for a collection must have is_active: true and is_can_collect: true. A service that can be used for a disbursement must have is_active: true and is_can_disburse: true.

6. Launch a collection

The standard flow uses three calls: intent, execute, then status.

curl -X POST "https://api.mysoleas.com/collection/intent" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "XAF",
    "transaction_uuid": "2f8b9a68-1ad3-4a0c-a187-40b91a4c44a1",
    "provider": "mtn_cmr",
    "channel": "PROVIDER",
    "customer_wallet": "670000000",
    "description": "Order MS-10045"
  }'

In the request, customer_wallet must not include the country calling code.

The response contains transaction_reference. Use this value to execute and track the transaction.

curl -X POST "https://api.mysoleas.com/collection/execute" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_reference": "TRX-20260728-000001",
    "invoice_reference": "MS-10045"
  }'

7. Track the status

Poll the status until you get a final state.

curl -X POST "https://api.mysoleas.com/collection/status" \
  -H "x-sp-auth-token: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_reference": "TRX-20260728-000001"
  }'

Final states are COMPLETED, SUCCESS, FAILED, CANCELLED, and REFUNDED.

Get started

Payments

Catalog

1. Prepare your domains

2. Create an application in SoleasPay

3. Get a gateway token

4. Call the gateway

5. Choose a service

6. Launch a collection

7. Track the status

​1. Prepare your domains

​2. Create an application in SoleasPay

​3. Get a gateway token

​4. Call the gateway

​5. Choose a service

​6. Launch a collection

​7. Track the status

1. Prepare your domains

2. Create an application in SoleasPay

3. Get a gateway token

4. Call the gateway

5. Choose a service

6. Launch a collection

7. Track the status