YassirDocs

Payment Methods

Retrieve available payment methods for your integration

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"
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"
    }
  ]
}

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 in x-client-token — no x-client-secret needed.
Either way the response is scoped to that user (their balance and saved cards). See Authentication.

Query Parameters#

amountnumberrequired
Payment amount. Must be greater than 0.
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

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. For a saved card, id is the cardId to use when proceeding with a payment.
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.
List Payment Methods (with User Context)
curl "https://api.payment.yassir.io/api/v1/payment-methods?amount=2500" \
  -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"
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"
    },
    {
      "id": "1330fa89-4115-43b1-b34d-0e3df2e6a5ba",
      "name": "Card",
      "code": "STRIPE",
      "displayName": "Card",
      "image": "https://assets.yassir.com/card-logo.png",
      "archetype": "IN_SDK"
    },
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "visa *** 3456",
      "code": "STRIPE",
      "image": "https://assets.yassir.com/card-logo.png",
      "paymentOptionType": "card"
    }
  ]
}

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"
200 OK
{
  "data": { "publicKey": "pk_test_1234567890abcdefghijklmnopqrstuvwxyz" },
  "message": "Stripe public key retrieved successfully"
}