Payment Methods

Retrieve available payment methods for your integration, and set the customer's default

List Available Payment Methods#

Returns the payment methods available for your service in a given country. Use this endpoint to check which payment methods your service supports before displaying options to users.

This endpoint requires Bearer authentication using your Client ID and Client Secret encoded in Base64.

GET/api/v1/payment-methods/available

Bearer Token

List payment methods available for the authenticated service.

Query Parameters#

countryCodestringrequired

ISO 3166-1 alpha-2 country code. Example: DZ, MA, TN

Required Headers#

Authorizationstringrequired

Bearer authentication. Format: Bearer base64(client_id:client_secret)

Response Fields#

data[].idstringrequired

Unique identifier for the payment method.

data[].namestringrequired

Internal name of the payment method.

data[].codestringrequired

Payment method code used in subsequent API calls. Use this value as paymentMethodCode when creating a payment intent.

data[].displayNamestringrequired

Localized display name for the payment method.

data[].imagestringrequired

URL of the payment method logo/icon.

data[].archetypestringoptional

How to render this method: IN_SDK means render the payment form inline (e.g. card entry); REDIRECT means hand off to an external page/app and resume on return. Branch your UI on this field rather than a hardcoded method-code list.

Allowed values:

IN_SDKREDIRECT

data[].labelstringoptional

Tenant-specific display label overriding displayName, only present when one is configured for your service.

Filtering by Country

Payment methods vary by country. Always pass the correct countryCode to get the relevant options for your user.

List Available Payment Methods

curl "https://api.payment.yassir.io/api/v1/payment-methods/available?countryCode=DZ" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-platform: API"

curl "https://api.payment.yassir.io/api/v1/payment-methods/available?countryCode=DZ" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-platform: API"

200 OK

{
  "code": 200,
  "status": "success",
  "message": "payment methods listed successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Yassir Cash",
      "code": "WALLET_V2",
      "displayName": "Yassir Cash",
      "image": "https://assets.yassir.com/wallet-logo.png",
      "archetype": "IN_SDK"
    }
  ]
}

{
  "code": 200,
  "status": "success",
  "message": "payment methods listed successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Yassir Cash",
      "code": "WALLET_V2",
      "displayName": "Yassir Cash",
      "image": "https://assets.yassir.com/wallet-logo.png",
      "archetype": "IN_SDK"
    }
  ]
}

List Payment Methods (with User Context)#

Returns payment methods with user-specific information such as wallet balance. Use this endpoint when you have a payment intent and want to show personalized payment options to the user.

This list also includes the user's saved cards as individual selectable items (alongside the payment method types such as WALLET_V2 for Yassir Cash and the card method). A saved card is identified by paymentOptionType: "card" and a display name like visa *** 3456; its id is the cardId you pass when charging a saved card. The /available endpoint above does not include saved cards.

GET/api/v1/payment-methods

Bearer Token

List payment methods with user-specific details (e.g. wallet balance).

Two ways to authenticate this endpoint

From your web page / SDK (merchant_auth): your publishable key (Authorization: Bearer pk_yassir_...) plus the payment's x-client-secret.
On behalf of a signed-in customer (user_auth): the customer's access token directly in the Authorization header (Authorization: Bearer <customer_access_token>) — no x-client-secret needed.

Either way the response is scoped to that user (their balance and saved cards). See Authentication.

Query Parameters#

amountnumberoptional

Payment amount. Must be greater than 0. Required for user_auth (returns 400 if omitted) — no payment intent exists yet at this point in that flow. Optional for merchant_auth: it is derived server-side from the transaction linked to your payment intent, so you can omit it entirely. If you do pass it and it disagrees with the intent's actual amount, the supplied value is ignored (not an error) — the real amount is always used.

actionCurrencyCodestringoptional

Currency code for the payment. Example: DZD, MAD

actionCountryCodestringoptional

Country code where the action takes place.

Required Headers#

Authorizationstringrequired

From the browser / SDK, your publishable key: Bearer pk_yassir_... (merchant_auth). It pairs with x-client-secret below — see Authentication.

x-client-secretstringrequired

The client secret returned when creating a payment intent. Together with the publishable key it authenticates the request and links it to the user who owns the payment intent.

x-servicestringoptional

Required for user_auth. Ignored for merchant_auth — the service is derived from your publishable key instead, so a caller cannot widen scope by sending a different value.

x-country-codestringoptional

Required for user_auth (ISO 3166-1 alpha-3, e.g. DZA). Ignored for merchant_auth — the country is derived from the payment intent this request is scoped to.

x-platformstringrequired

The platform making the request.

Allowed values:

APIWEBANDROIDIOS

x-localestringoptional

User locale for localized payment method names. Example: en_US, fr_FR, ar_DZ

Originstringoptional

Required for merchant_auth from a browser. Must match one of the service's allow-listed origins, or the request is rejected with 403 origin_not_allowed.

Getting the Client Secret#

The x-client-secret is returned in the response when you create a payment intent:

How to get client secret

// Create a payment intent first
const intent = await fetch("/api/v1/payments/intents?countryCode=DZA", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    actionId: "unique-order-id",
    amount: 2500,
    actionCurrencyCode: "DZD",
    actionCountryCode: "DZA",
    userId: "+213555123456",
  }),
});

const { data } = await intent.json();
// data.clientSecret => "pa_xxxxxxxx_secret_xxxxxxxx"
// Use this as the x-client-secret header

// Create a payment intent first
const intent = await fetch("/api/v1/payments/intents?countryCode=DZA", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    actionId: "unique-order-id",
    amount: 2500,
    actionCurrencyCode: "DZD",
    actionCountryCode: "DZA",
    userId: "+213555123456",
  }),
});

const { data } = await intent.json();
// data.clientSecret => "pa_xxxxxxxx_secret_xxxxxxxx"
// Use this as the x-client-secret header

Response Fields#

data[].idstringrequired

Unique identifier for the payment method.

data[].namestringrequired

Internal name of the payment method.

data[].codestringrequired

Payment method code. Use this as paymentMethodCode when proceeding with payment.

data[].displayNamestringrequired

Localized display name for the payment method. Changes based on x-locale header.

data[].imagestringrequired

URL of the payment method logo/icon.

data[].balancenumberoptional

User's wallet balance (only present for wallet-type payment methods like WALLET_V2).

data[].currencystringoptional

Currency of the wallet balance.

data[].paymentOptionTypestringoptional

Distinguishes the kind of item. card marks one of the user's saved cards; wallet marks the wallet; paymentMethod marks any other payment method. For a saved card, id is the cardId to use when proceeding with a payment. See Payment Option Types.

Allowed values:

walletpaymentMethodcard

data[].archetypestringoptional

How to render this method: IN_SDK for an inline payment form, REDIRECT for an external handoff. Absent on individual saved-card items.

Allowed values:

IN_SDKREDIRECT

data[].labelstringoptional

Tenant-specific display label overriding displayName, only present when one is configured for your service.

data[].isDefaultbooleanrequired

true only for the customer's default payment method or saved card, set with Set Default Payment Method. At most one item is true. Every item is false when the customer has no default, or when the default is not in this list. For a saved card default, only the card is true, not its card payment method.

List Payment Methods (with User Context)

# merchant_auth: amount is derived from the payment intent, so it can be omitted
curl "https://api.payment.yassir.io/api/v1/payment-methods" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_xxxxxxxx_secret_xxxxxxxx" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: WEB" \
  -H "Origin: https://yourapp.com"

# user_auth: amount is still required
curl "https://api.payment.yassir.io/api/v1/payment-methods?amount=2500" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API"

# merchant_auth: amount is derived from the payment intent, so it can be omitted
curl "https://api.payment.yassir.io/api/v1/payment-methods" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_xxxxxxxx_secret_xxxxxxxx" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: WEB" \
  -H "Origin: https://yourapp.com"

# user_auth: amount is still required
curl "https://api.payment.yassir.io/api/v1/payment-methods?amount=2500" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API"

200 OK — wallet, card method, and a saved card

{
  "code": 200,
  "status": "success",
  "message": "payment methods listed successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Yassir Cash",
      "code": "WALLET_V2",
      "displayName": "Yassir Cash",
      "image": "https://assets.yassir.com/wallet-logo.png",
      "balance": 15000,
      "currency": "DZD",
      "paymentOptionType": "wallet",
      "archetype": "IN_SDK",
      "isDefault": false
    },
    {
      "id": "1330fa89-4115-43b1-b34d-0e3df2e6a5ba",
      "name": "Card",
      "code": "STRIPE",
      "displayName": "Card",
      "image": "https://assets.yassir.com/card-logo.png",
      "paymentOptionType": "paymentMethod",
      "archetype": "IN_SDK",
      "isDefault": false
    },
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "visa *** 3456",
      "code": "STRIPE",
      "image": "https://assets.yassir.com/card-logo.png",
      "paymentOptionType": "card",
      "isDefault": true
    }
  ]
}

{
  "code": 200,
  "status": "success",
  "message": "payment methods listed successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Yassir Cash",
      "code": "WALLET_V2",
      "displayName": "Yassir Cash",
      "image": "https://assets.yassir.com/wallet-logo.png",
      "balance": 15000,
      "currency": "DZD",
      "paymentOptionType": "wallet",
      "archetype": "IN_SDK",
      "isDefault": false
    },
    {
      "id": "1330fa89-4115-43b1-b34d-0e3df2e6a5ba",
      "name": "Card",
      "code": "STRIPE",
      "displayName": "Card",
      "image": "https://assets.yassir.com/card-logo.png",
      "paymentOptionType": "paymentMethod",
      "archetype": "IN_SDK",
      "isDefault": false
    },
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "visa *** 3456",
      "code": "STRIPE",
      "image": "https://assets.yassir.com/card-logo.png",
      "paymentOptionType": "card",
      "isDefault": true
    }
  ]
}

Set Default Payment Method#

Saves one payment method or one saved card as the customer's default. A customer has at most one default: setting a new one replaces the previous one, and setting the same one again also succeeds.

Send back the id and paymentOptionType of an item returned by List Payment Methods (with User Context). For a saved card, the id is the card id.

PUT/api/v1/payment-methods/default

Bearer Token

Set the customer's default payment method or saved card.

Two ways to authenticate this endpoint

As the customer (user_auth): the customer's access token in the Authorization header.
From your server (client_auth): your client credentials in Authorization, plus the customer's token in x-client-token. Without x-client-token the request is rejected with 401 customer_token_required.

A publishable key (merchant_auth) is not accepted: it is scoped to one payment, and a default belongs to the customer.

What can be the default

Only an item that List Payment Methods returns for the same x-service, x-country-code and x-platform: the wallet, a payment method, or one of the customer's saved cards. The wallet can be the default only when the customer's wallet is active (they have a wallet with a balance above 0). If the default saved card is deleted, the customer no longer has a default.

Request Body#

paymentOptionTypestringrequired

The paymentOptionType of the chosen item.

Allowed values:

walletpaymentMethodcard

idstringrequired

The id of the chosen item (a UUID). For a saved card, the card id.

Payment Option Types#

Every item of List Payment Methods has one of these paymentOptionType values:

`paymentOptionType`	What it is	What `id` is
`wallet`	The Yassir wallet (Yassir Cash, code `WALLET_V2`). It can be the default only when the customer's wallet is active.	The wallet payment method id
`paymentMethod`	Any other payment method, for example the card method (`STRIPE`), Wave or CIB/Dahabiya	The payment method id
`card`	One of the customer's saved cards, shown like `visa *** 3456`	The card id

Required Headers#

Authorizationstringrequired

Bearer <customer_access_token> for user_auth, or Bearer base64(client_id:client_secret) for client_auth.

x-client-tokenstringoptional

Required for client_auth: the customer's token. Not used with user_auth.

x-servicestringrequired

Your service code. It must match your credentials.

x-country-codestringrequired

ISO 3166-1 alpha-3 country code, e.g. DZA.

x-platformstringrequired

The platform making the request. Some methods depend on it, for example Apple Pay is not offered on Android.

Allowed values:

APIWEBANDROIDIOS

x-sdk-versionstringoptional

Required when x-platform is not API.

Response Fields#

data.paymentOptionTypestringrequired

The paymentOptionType of the new default.

Allowed values:

walletpaymentMethodcard

data.idstringrequired

The id of the new default.

data.paymentMethodCodestringrequired

The payment method code, for example STRIPE for a saved card.

Errors#

HTTP	`errors`	Cause
`400`	`payment_option_not_available`	The item exists but is not offered for this service, country and platform, or `paymentOptionType` does not match it, or the customer's wallet is not active.
`400`	validation messages	Invalid body or headers.
`401`	`customer_token_required`	`client_auth` call without `x-client-token`.
`403`		The customer is inactive.
`404`	`payment_option_not_found`	No such payment method, or no such saved card for this customer. Another customer's card gives the same error.

Set Default Payment Method

# user_auth: the customer's access token
curl -X PUT "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API" \
  -d '{ "paymentOptionType": "card", "id": "d290f1ee-6c54-4b01-90e6-d701748f0851" }'

# client_auth: your credentials plus the customer's token
curl -X PUT "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-client-token: CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API" \
  -d '{ "paymentOptionType": "paymentMethod", "id": "1330fa89-4115-43b1-b34d-0e3df2e6a5ba" }'

# user_auth: the customer's access token
curl -X PUT "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API" \
  -d '{ "paymentOptionType": "card", "id": "d290f1ee-6c54-4b01-90e6-d701748f0851" }'

# client_auth: your credentials plus the customer's token
curl -X PUT "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-client-token: CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API" \
  -d '{ "paymentOptionType": "paymentMethod", "id": "1330fa89-4115-43b1-b34d-0e3df2e6a5ba" }'

200 OK

{
  "code": 200,
  "status": "success",
  "message": "default payment method set successfully",
  "data": {
    "paymentOptionType": "card",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "paymentMethodCode": "STRIPE"
  }
}

{
  "code": 200,
  "status": "success",
  "message": "default payment method set successfully",
  "data": {
    "paymentOptionType": "card",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "paymentMethodCode": "STRIPE"
  }
}

404 Not Found

{
  "code": 404,
  "status": "failed",
  "message": "saved card not found",
  "errors": ["payment_option_not_found"]
}

{
  "code": 404,
  "status": "failed",
  "message": "saved card not found",
  "errors": ["payment_option_not_found"]
}

Get Default Payment Method#

Returns the customer's default as the same item that List Payment Methods (with User Context) returns for it: same fields, same id and paymentOptionType, and isDefault: true.

data is null when the customer has no default, or when the default is not offered for this x-service, x-country-code and x-platform. Calling it never creates anything.

GET/api/v1/payment-methods/default

Bearer Token

Get the customer's default payment method or saved card.

Authentication

The same as Set Default Payment Method: the customer's access token (user_auth), or your client credentials with the customer's token in x-client-token (client_auth).

Wallet balance

For the wallet, the balance fields (balance, currency, walletDisplayState) are only in List Payment Methods, because they depend on the payment amount.

Headers#

Authorizationstringrequired

Bearer <customer_access_token> for user_auth, or Bearer base64(client_id:client_secret) for client_auth.

x-client-tokenstringoptional

Required for client_auth: the customer's token.

x-servicestringrequired

Your service code. It must match your credentials.

x-country-codestringrequired

ISO 3166-1 alpha-3 country code, e.g. DZA.

x-platformstringrequired

The platform making the request.

Allowed values:

APIWEBANDROIDIOS

x-sdk-versionstringoptional

Required when x-platform is not API.

x-localestringoptional

Locale of the display name. Example: en_US, fr_CA. Default en_US.

Response Fields#

dataobject | nullrequired

The default item, with the fields of a List Payment Methods item, or null.

data.paymentOptionTypestringoptional

See Payment Option Types.

Allowed values:

walletpaymentMethodcard

data.idstringoptional

The payment method id, or the card id for a saved card.

data.isDefaultbooleanoptional

Always true, like the same item in List Payment Methods.

Errors#

HTTP	Cause
`400`	Invalid headers, or the service or its tenant is not active.
`401`	`customer_token_required`: `client_auth` without `x-client-token`.
`403`	The customer is inactive.
`404`	Country not found.

Get Default Payment Method

curl "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API"

curl "https://api.payment.yassir.io/api/v1/payment-methods/default" \
  -H "Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN" \
  -H "x-service: your-service-code" \
  -H "x-country-code: DZA" \
  -H "x-platform: API"

200 OK: a saved card

{
  "code": 200,
  "status": "success",
  "message": "default payment method retrieved successfully",
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "code": "STRIPE",
    "name": "visa *** 3456",
    "image": "https://assets.yassir.com/card-logo.png",
    "paymentOptionType": "card",
    "isDefault": true
  }
}

{
  "code": 200,
  "status": "success",
  "message": "default payment method retrieved successfully",
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "code": "STRIPE",
    "name": "visa *** 3456",
    "image": "https://assets.yassir.com/card-logo.png",
    "paymentOptionType": "card",
    "isDefault": true
  }
}

200 OK: no default

{
  "code": 200,
  "status": "success",
  "message": "no default payment method",
  "data": null
}

{
  "code": 200,
  "status": "success",
  "message": "no default payment method",
  "data": null
}

Get Stripe Public Key#

Returns the Stripe publishable key to initialize Stripe.js / Stripe Elements client-side. Resolved per tenant, service, and country — not a single fixed key for the whole platform.

GET/api/v1/payment-methods/stripe/pk

Bearer Token

Get the Stripe publishable key to use for this service/country (or payment intent, under merchant_auth).

Required Headers#

Authorizationstringrequired

Your client_auth/user_auth credential, or a publishable key (Bearer pk_yassir_...) for merchant_auth.

x-client-secretstringoptional

Required for merchant_auth only.

x-servicestringoptional

Required for client_auth/user_auth. Ignored for merchant_auth — derived from the publishable key.

x-country-codestringoptional

Required for client_auth/user_auth (ISO 3166-1 alpha-3, e.g. DZA). Ignored for merchant_auth — derived from the resolved payment intent.

Get Stripe Public Key

curl "https://api.payment.yassir.io/api/v1/payment-methods/stripe/pk" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_xxxxxxxx_secret_xxxxxxxx"

curl "https://api.payment.yassir.io/api/v1/payment-methods/stripe/pk" \
  -H "Authorization: Bearer pk_yassir_a1b2c3d4e5f67890a1b2c3d4e5f67890" \
  -H "x-client-secret: pa_xxxxxxxx_secret_xxxxxxxx"

200 OK

{
  "data": { "publicKey": "pk_test_1234567890abcdefghijklmnopqrstuvwxyz" },
  "message": "Stripe public key retrieved successfully"
}

{
  "data": { "publicKey": "pk_test_1234567890abcdefghijklmnopqrstuvwxyz" },
  "message": "Stripe public key retrieved successfully"
}