Authentication

Learn how to authenticate your API requests

Overview#

Yassir Payment uses three authentication modes. The mode is selected by the credential you put in the Authorization header — the API detects which one you sent. Which mode you use depends on where the call is made from and who it is on behalf of.

Mode	Credential(s)	Used from
`client_auth`	`Authorization: Bearer base64(client_id:client_secret)`	Your server (create intent, capture, release, refund)
`merchant_auth`	`Authorization: Bearer pk_yassir_...` + `x-client-secret`	Your web page / SDK, scoped to one payment (proceed, check, list payment methods with user context)
`user_auth`	Customer access token (`x-client-token` or `Authorization: Bearer`)	A signed-in customer (list and delete saved cards)

Authentication vs. authorization

These modes are about authentication — proving who is calling. They also affect authorization: merchant_auth and user_auth scope the response to a specific user's data (their wallet balance, their saved cards), which your service credentials alone cannot see.

1. Server-to-server (`client_auth`)#

Your Client ID and Client Secret (issued during onboarding), Base64-encoded as a Bearer token. Use this for backend calls: creating a payment intent, capturing, releasing, and refunding.

Keep these server-side

Never expose your Client ID and Client Secret in frontend code. They authenticate your whole service — use them only from your server.

client_auth — create a payment intent

curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents?countryCode=DZA" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "x-platform: API" \
  -H "x-service: YOUR_SERVICE" \
  -d '{
    "actionId": "order_12345",
    "amount": 1500.00,
    "actionCurrencyCode": "DZD",
    "actionCountryCode": "DZA",
    "userId": "+213555123456"
  }'

curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents?countryCode=DZA" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -H "x-platform: API" \
  -H "x-service: YOUR_SERVICE" \
  -d '{
    "actionId": "order_12345",
    "amount": 1500.00,
    "actionCurrencyCode": "DZD",
    "actionCountryCode": "DZA",
    "userId": "+213555123456"
  }'

2. Browser / SDK (`merchant_auth`)#

Requests made from your web page or SDK use two credentials together:

Your publishable key (pk_yassir_..., issued during onboarding) in the Authorization header. It identifies your service.
The payment client secret in the x-client-secret header. This is the clientSecret returned when you create a payment intent (format pa_{id}_secret_{hex}). It scopes the request to that one payment.

You need both — the payment client secret alone is not accepted in this mode. This is what unlocks "user context" from the browser: reading the user's wallet balance and saved cards, proceeding, and checking status.

Why the publishable key is browser-safe

The publishable key is designed to be embedded in your web page. On its own it can do nothing — it only works paired with a specific payment's client secret, requests must come from an allow-listed origin (your domain, configured during onboarding), and it only ever scopes to your own service's payments.

merchant_auth — publishable key + payment client secret

# The client secret comes from the Create Payment Intent response:
#   data.clientSecret => "pa_123e4567_secret_a1b2c3d4e5f6"

curl "https://api.payment.yassir.io/api/v1/payment-methods?amount=2500" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_123e4567_secret_a1b2c3d4e5f6" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: WEB" \
  -H "Origin: https://yourapp.com"

# The client secret comes from the Create Payment Intent response:
#   data.clientSecret => "pa_123e4567_secret_a1b2c3d4e5f6"

curl "https://api.payment.yassir.io/api/v1/payment-methods?amount=2500" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_123e4567_secret_a1b2c3d4e5f6" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: WEB" \
  -H "Origin: https://yourapp.com"

3. Signed-in customer (`user_auth`)#

Requests made on behalf of a specific signed-in customer authenticate with that customer's access token, sent in the x-client-token header (or as a Bearer Authorization token). Use this for customer-scoped endpoints such as listing and deleting the customer's saved cards.

user_auth — list a customer's saved cards

curl "https://api.payment.yassir.io/api/v1/cards" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-client-token: CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: YOUR_SERVICE" \
  -H "x-platform: API"

curl "https://api.payment.yassir.io/api/v1/cards" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-client-token: CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: YOUR_SERVICE" \
  -H "x-platform: API"

Getting a customer access token#

Your server exchanges its client credentials and a registered customer's id for a customer access token (and a refresh token). Register the customer first via the Customers API to obtain the customerId.

Generate — POST /api/v1/customer-access-token, body { "customerId": "..." }, authenticated with your client credentials. Returns accessToken, refreshToken, and their expiries (in seconds).
Refresh — POST /api/v1/customer-access-token/refresh, body { "refreshToken": "...", "accessToken": "..." }.
Revoke — DELETE /api/v1/customer-access-token/revoke, body { "accessToken": "..." }.

Generate a customer access token

# Exchange your client credentials + a customerId for a customer access token
curl -X POST "https://api.payment.yassir.io/api/v1/customer-access-token" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }'

# 201 Created
{
  "data": {
    "accessToken": "eyJhbGciOiJI...",
    "refreshToken": "eyJhbGciOiJI...",
    "accessTokenExpiresIn": 3600,
    "refreshTokenExpiresIn": 2592000
  },
  "message": "Successfully generated access token and refresh token"
}

# Exchange your client credentials + a customerId for a customer access token
curl -X POST "https://api.payment.yassir.io/api/v1/customer-access-token" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }'

# 201 Created
{
  "data": {
    "accessToken": "eyJhbGciOiJI...",
    "refreshToken": "eyJhbGciOiJI...",
    "accessTokenExpiresIn": 3600,
    "refreshTokenExpiresIn": 2592000
  },
  "message": "Successfully generated access token and refresh token"
}

Which mode does each endpoint use?#

A typical card / wallet checkout creates the intent server-side (client_auth), then proceeds and checks from the browser (merchant_auth).

Endpoint	Mode(s)
Create payment intent	`client_auth`
Proceed, Check	`client_auth`, `merchant_auth`, or `user_auth`
Capture, Release, Refund	`client_auth`
List payment methods (`/available`)	`client_auth`
List payment methods (user context)	`merchant_auth` or `user_auth`
List / delete cards	`user_auth`

Common headers#

In addition to the credentials for your chosen mode, most requests include these headers:

x-servicestringrequired

Your service identifier provided during onboarding.

x-platformstringrequired

The platform making the request.

Allowed values:

APIWEBANDROIDIOS

Content-Typestringrequired

Must be application/json for requests with a body.

x-country-codestringoptional

ISO 3166-1 alpha-3 country code. Examples: DZA, MAR, TUN

x-localestringoptional

Locale for localized responses. Examples: en_US, fr_FR, ar_DZ

Environments#

We provide two environments for integration:

Environment	Base URL	Purpose
Sandbox	`https://stg-api.payment.yassir.io`	Testing and development
Production	`https://api.payment.yassir.io`	Live transactions

Test Credentials

Use your sandbox credentials during development. Test in the sandbox environment before going live.