YassirDocs

Payment Intents

Create, process, and track payments through their lifecycle

A Payment Intent represents a single payment attempt. The typical flow is:

  1. Create a payment intent with the amount, currency, and capture method
  2. Proceed with Yassir Cash as the payment method
  3. Handle any redirects (OTP verification)
  4. Check the payment status

For pre-authorization flows, create the intent with captureMethod: "RESERVATION", then capture or release the funds later.

Authentication by endpoint

Create, capture, release, and refund are server-side only — they use client_auth (your client credentials). Proceed and Check also accept merchant_auth (browser / SDK: publishable key + x-client-secret) and user_auth (a signed-in customer's token). Full details in Authentication.

Create Payment Intent#

Creates a new payment intent. Returns a paymentId and clientSecret that you use in subsequent calls.

POST/api/v1/payments/intents
Bearer Token
Create a new payment intent to begin the payment process.

Query Parameters#

countryCodestringrequired
ISO 3166-1 alpha-3 country code. Example: DZA

Request Body#

actionIdstringrequired
Your unique identifier for this transaction (e.g., order ID). Used for idempotency.
amountnumberrequired
Payment amount in the currency's standard unit.
actionCurrencyCodestringrequired
ISO 4217 currency code. Example: DZD, MAD, USD
actionCountryCodestringrequired
ISO 3166-1 alpha-3 country code where the action takes place.
userIdstringrequired
The customer's phone number (must match a registered customer). See Customers API to register customers first.
captureMethodstringoptional
Controls when the payment is captured. Defaults to DIRECT.
DIRECT — Capture immediately when the payment is processed.
RESERVATION — Reserve the funds and capture later via the Capture endpoint.
transactionTypestringoptional
Optional transaction type. Use QR_CODE to create a QR wallet payment intent. For regular payments, omit this field.
metaDataobjectoptional
Optional metadata object. Include paymentCheckoutId for tracking.

Required Headers#

Authorizationstringrequired
Bearer authentication. Format: Bearer base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier provided during onboarding.
Content-Typestringrequired
Must be application/json.

Response#

data.paymentIdstringrequired
Unique payment identifier (UUID). Use this in all subsequent Proceed, Check, Capture, and Release calls.
data.clientSecretstringrequired
Payment-scoped secret for SDK authentication. Format: pa_{id}_secret_{hex}
data.statusstringrequired
Current payment action status. Will be CREATED after initialization.
data.amountnumberrequired
The payment amount.
data.currencystringrequired
The payment currency code (e.g., DZD).
data.expiresAtstringrequired
ISO 8601 expiration timestamp. The payment must be processed before this time (30 minutes from creation).
Create 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": "user_abc123",
    "captureMethod": "DIRECT"
  }'
201 Created
{
  "data": {
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "clientSecret": "pa_123e4567_secret_a1b2c3d4e5f6a1b2c3d4e5f6",
    "status": "CREATED",
    "amount": 1500.00,
    "currency": "DZD",
    "expiresAt": "2026-02-18T10:30:00.000Z"
  },
  "message": "payment initiated successfully"
}
QR Create Payment Intent Body
// QR wallet payment intent
{
  "actionId": "merchant-order-123",
  "amount": 1200,
  "actionCurrencyCode": "DZD",
  "actionCountryCode": "DZA",
  "transactionType": "QR_CODE",
  "metaData": {
    "paymentCheckoutId": "checkout-123"
  }
}

Proceed with Payment#

Submits the payment for processing with Yassir Cash. The response may indicate that additional user action is required (OTP verification).

POST/api/v1/payments/intents/:id/proceed
Bearer Token
Process the payment using Yassir Cash.

URL Parameters#

idstringrequired
The paymentId returned from the Create Payment Intent endpoint.

Request Body#

paymentMethodCodestringrequired
The payment method to use. Use WALLET_V2 for Yassir Cash, or STRIPE for Visa / Mastercard card payments. Read the exact value from List Payment Methods.
cardIdstringoptional
For card payments only. The ID of a saved card to charge. Omit it to have the buyer enter a new card on the hosted page.
redirectUrlstringoptional
For card payments only. Where the buyer's browser is sent after the hosted card page. Must be an http/https URL. See Card Payments.

Paying by card (Visa / Mastercard)

For a card payment, proceed with paymentMethodCode: "STRIPE". The response has statusCode: 12 with a payUrl; redirect the buyer there to enter their card (or complete 3D Secure for a saved card). The full flow, including the redirect response, is in the Card Payments guide.

Required Headers#

Authorizationstringrequired
The credential for your auth mode (see below): Bearer base64(client_id:client_secret) for client_auth, Bearer pk_yassir_... for merchant_auth, or the customer token for user_auth.
x-client-secretstringoptional
Required for merchant_auth only. The payment's clientSecret from Create Payment Intent (format pa_{id}_secret_{hex}). Ignored in client_auth and user_auth.
x-servicestringoptional
Required for client_auth/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-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-country-codestringoptional
Deprecated. No longer used to resolve country — the transaction's persisted country is used instead. Retained only for mismatch detection ahead of removal in a follow-up release; clients may stop sending it. ISO 3166-1 alpha-3, e.g. DZA.
x-localestringoptional
Locale for localized responses. Example: en_US

Auth modes for Proceed

  • client_auth (server): Authorization: Bearer base64(client_id:client_secret).
  • merchant_auth (browser / SDK): Authorization: Bearer pk_yassir_... + x-client-secret + an allow-listed Origin.
  • user_auth (signed-in customer): the customer's access token in x-client-token.

merchant_auth error responses

Requests under merchant_auth can additionally fail with:
  • 401 invalid_credentials — malformed/unresolvable publishable key or client secret, secret mismatch, or an attempt to access another merchant's payment intent.
  • 403 origin_not_allowed — the request's Origin header is not on your service's allow-list. Register your checkout page's origin before going live.
  • 410 intent_expired — a non-terminal intent is more than 30 minutes (plus a 30s grace window) past creation. Create a new intent rather than retrying the same one.
  • 429 rate_limited — per-publishable-key (600 req/min) or per-client-secret (120 req/min) limit exceeded. Back off rather than retrying immediately, especially when polling Check Payment Status.
These error codes deliberately don't distinguish finer causes (e.g. "wrong secret" vs. "intent doesn't exist") to avoid letting a caller enumerate valid intent ids.

Handling OTP Verification

When require3DS is true, redirect the user to the payUrl. Yassir handles the entire OTP flow — sending the SMS, showing the verification page, and validating the code. Append a returnUrl query parameter so the user is redirected back to your app after verification.

See the OTP Verification guide for the complete redirect flow.

Response#

data.require3DSbooleanrequired
Whether OTP/3DS verification is required. If true, redirect the user to payUrl.
data.statusCodenumberrequired
Payment status code. See the status codes table below.
data.statusstringrequired
Human-readable status description from the payment provider.
data.metadata.payUrlstringoptional
OTP verification URL. Only present when require3DS is true. Append your returnUrl as a query parameter.
data.metadata.qrImageUrlstringoptional
QR image URL for QR wallet payments. Present when the intent was created with transactionType: "QR_CODE" and proceeded with WALLET_V2. Display this URL to the customer.

Status Codes#

statusCodeMeaningAction Required
2SuccessPayment completed. Show success to user.
3RejectedPayment failed. Show error and allow retry.
12Requires ActionRedirect user to payUrl for OTP verification.
13Pre-AuthorizedFunds reserved. Use Capture or Release endpoint.
Proceed with Payment
# client_auth (server-side). For browser/SDK use merchant_auth:
#   Authorization: Bearer pk_yassir_...  +  x-client-secret: pa_..._secret_...
curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents/123e4567-e89b-12d3-a456-426614174000/proceed" \
  -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" \
  -H "x-country-code: DZA" \
  -d '{
    "paymentMethodCode": "WALLET_V2"
  }'
200 OK — Requires Action (OTP)
// statusCode: 12 → Requires OTP verification
{
  "data": {
    "require3DS": true,
    "statusCode": 12,
    "status": "Require Authentication Action",
    "metadata": {
      "payUrl": "https://otp.payment.yassir.io/otp/verify?requestId=...&phone=213555123456&amount=1500&currency=DZD"
    }
  },
  "message": "payment proceeded successfully"
}
200 OK — Success
// statusCode: 2 → Payment succeeded immediately
{
  "data": {
    "require3DS": false,
    "statusCode": 2,
    "status": "The amount was deposited successfully",
    "metadata": {
      "payUrl": ""
    }
  },
  "message": "payment proceeded successfully"
}
200 OK — Rejected
// statusCode: 3 → Payment rejected
{
  "data": {
    "require3DS": false,
    "statusCode": 3,
    "status": "Transaction was rejected",
    "metadata": {
      "payUrl": ""
    }
  },
  "message": "payment proceeded successfully"
}
200 OK — QR Wallet
// QR wallet payment → display qrImageUrl and wait for statusCode: 2
{
  "data": {
    "require3DS": false,
    "metadata": {
      "qrImageUrl": "https://storage.googleapis.com/.../qr-codes/2fddefa2-f137-4afd-b6a8-b1623d86b115.png?..."
    }
  },
  "message": "payment proceeded successfully"
}
200 OK — Card (redirect to hosted page)
// Card → redirect the buyer to payUrl to enter their card
{
  "data": {
    "require3DS": true,
    "statusCode": 12,
    "status": "Require card details",
    "metadata": {
      "payUrl": "https://<yassir-hosted-card-page>/..."
    }
  },
  "message": "payment proceeded successfully"
}

Finalize Stripe Payment#

Called by the buyer's browser right after stripe.confirmCardPayment succeeds on the Yassir-hosted card-entry page (the payUrl a card Proceed response redirects to). Most integrations never call this directly — the hosted page does it for you — but it's documented here for custom card-entry integrations.

Idempotent on paymentIntentId: this same handler is also invoked by the payment_intent.succeeded Stripe webhook, so a race between the browser call and the webhook still results in exactly one saved card and one succeeded transaction.

POST/api/v1/payments/intents/:paymentActionId/stripe-finalize
API Key
Confirm a Stripe card payment against its payment intent.

URL Parameters#

paymentActionIdstringrequired
The PaymentAction ID returned at Create Payment Intent.

Request Body#

paymentIntentIdstringrequired
The Stripe PaymentIntent ID confirmed on the hosted tokenization page (pi_...).
externalCardIdstringrequired
The Stripe PaymentMethod ID attached to the confirmed PaymentIntent (pm_...).

Required Headers#

x-client-secretstringrequired
The payment intent's clientSecret (format pa_{id}_secret_{hex}).

A different, narrower credential scheme

Unlike Proceed and Check, this endpoint does not use the publishable-key + client-secret merchant_auth pair — only x-client-secret, compared against the paymentActionId in the URL. It's reached exclusively via a payUrl that core itself issued for that one payment intent, so the per-intent secret alone is sufficient proof of ownership.

Response#

data.statusstringrequired
succeeded on success.
data.paymentIdstringrequired
The transaction ID.
data.cardIdstringoptional
The saved card's ID, when the buyer opted to save the card.
Finalize Stripe Payment
curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents/123e4567-e89b-12d3-a456-426614174000/stripe-finalize" \
  -H "x-client-secret: pa_xxxxxxxx_secret_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentIntentId": "pi_3OabcXYZ1234567890",
    "externalCardId": "pm_1OabcXYZ1234567890"
  }'
200 OK
{
  "data": {
    "status": "succeeded",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "cardId": "123e4567-e89b-12d3-a456-426614174001"
  },
  "message": "payment finalised successfully"
}

Check Payment Status#

Retrieves the current status of a payment intent. Use this after the user returns from a redirect to confirm the payment result.

GET/api/v1/payments/intents/:id/check
Bearer Token
Check the current status of a payment intent.

URL Parameters#

idstringrequired
The paymentId to check.

Required Headers#

Authorizationstringrequired
The credential for your auth mode: Bearer base64(client_id:client_secret) (client_auth), Bearer pk_yassir_... (merchant_auth), or the customer token (user_auth).
x-client-secretstringoptional
Required for merchant_auth only. The payment's clientSecret from Create Payment Intent. Ignored in client_auth and user_auth.
x-servicestringoptional
Required for client_auth/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-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS

Check accepts the same three auth modes as Proceed. See Authentication.

Response#

data.statusCodenumberrequired
Payment status code (2 = succeeded, 3 = rejected,12 = requires action, 13 = pre-authorized).
data.paymentMethodNamestringrequired
The payment method code used (e.g., WALLET_V2).
data.amountnumberrequired
The captured or payment amount.
data.currencyCodestringrequired
The payment currency code (e.g., DZD).
data.endUserMessagestringrequired
Human-readable status message suitable for displaying to the user.
data.supportInfoobjectoptional
Support contact information with email and phoneNumber.
data.lastUpdatestringoptional
ISO 8601 timestamp of the last status update.
Check Payment Status
# client_auth (server-side). For browser/SDK use merchant_auth
# (Authorization: Bearer pk_yassir_... + x-client-secret) or user_auth.
curl -X GET "https://api.payment.yassir.io/api/v1/payments/intents/123e4567-e89b-12d3-a456-426614174000/check" \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-platform: API" \
  -H "x-service: YOUR_SERVICE"
200 OK
{
  "data": {
    "statusCode": 2,
    "paymentMethodName": "WALLET_V2",
    "amount": 1500,
    "currencyCode": "DZD",
    "endUserMessage": "Payment completed successfully",
    "supportInfo": {
      "email": "support@yassir.com",
      "phoneNumber": "+213000000000"
    },
    "lastUpdate": "2025-01-15T10:30:00.000Z"
  },
  "message": "payment status retrieved successfully"
}
200 OK — QR Proceeding
// QR wallet payment still waiting for customer confirmation
{
  "data": {
    "statusCode": 1,
    "paymentMethodName": "WALLET_V2",
    "amount": 1200,
    "currencyCode": "DZD",
    "paymentOrderId": "2fddefa2-f137-4afd-b6a8-b1623d86b115",
    "microServiceTransactionId": "",
    "endUserMessage": {
      "en": "Proceeding",
      "fr": "En cours",
      "ar": "قيد المعالجة"
    },
    "approvalCode": null
  },
  "message": "payment checked successfully"
}

Capture Payment#

Captures a pre-authorized payment. Only available for payment intents created with captureMethod: "RESERVATION" that have been successfully pre-authorized (statusCode 13).

You can capture less than the reserved amount (partial capture). The remaining unreserved amount is automatically released back to the user.

POST/api/v1/payments/intents/:id/capture
Bearer Token
Capture a pre-authorized payment.

URL Parameters#

idstringrequired
The paymentId of the pre-authorized payment.

Request Body#

amountnumberoptional
Amount to capture. Must be less than or equal to the reserved amount. If omitted, the full reserved amount is captured.

Required Headers#

Authorizationstringrequired
Bearer authentication. Format: Bearer base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.

Partial Capture

If you capture less than the reserved amount, the difference is automatically released back to the user's wallet. For example, if you reserved 5000 DZD and capture 4500 DZD, the remaining 500 DZD is released automatically.
Capture Payment
# Capture a partial amount (e.g., reserved 5000, capture 4500)
curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents/123e4567-e89b-12d3-a456-426614174000/capture" \
  -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 '{
    "amount": 4500.00
  }'
200 OK
{
  "data": {
    "status": "The amount was deposited successfully",
    "statusCode": 2,
    "metaData": {
      "payUrl": ""
    }
  },
  "message": "payment captured successfully"
}

Release Payment#

Releases a pre-authorized payment without capturing any funds. The full reserved amount is returned to the user's wallet.

POST/api/v1/payments/intents/:id/release
Bearer Token
Release a pre-authorized payment without capturing.

URL Parameters#

idstringrequired
The paymentId of the pre-authorized payment.

Required Headers#

Authorizationstringrequired
Bearer authentication. Format: Bearer base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.
Release Payment
curl -X POST "https://api.payment.yassir.io/api/v1/payments/intents/123e4567-e89b-12d3-a456-426614174000/release" \
  -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 '{}'
200 OK
{
  "data": {
    "status": "Reversed",
    "statusCode": 10,
    "metaData": {
      "payUrl": ""
    }
  },
  "message": "payment released successfully"
}

Refund Payment#

Refund a completed payment, either fully or partially. Yassir Cash supports multiple partial refunds on a single payment — each refund reduces the remaining refundable balance.

POST/api/v1/payments/:paymentId/refund
Bearer Token
Refund a completed payment.

URL Parameters#

paymentIdstringrequired
The payment ID to refund.

Request Body#

descriptionstringrequired
Reason for the refund.
amountnumberoptional
Amount to refund. If omitted, the full remaining refundable amount is refunded. For partial refunds, specify the amount to refund.
reasonstringoptional
Short reason code for the refund.

Response Fields#

Full and partial refunds return the same shape. Tell them apart from the amounts: when totalRefundedAmount equals transactionAmount the payment is fully refunded; while it is less, the payment is partially refunded and remainingRefundableAmount is still refundable.

data.statusCodenumberoptional
Refund status code — 4 (refunded) for manual refunds, 14 for auto-refunds. It does not distinguish full from partial.
data.statusstringoptional
Human-readable refund status.
data.refundedAmountnumberoptional
Amount refunded by this request.
data.totalRefundedAmountnumberoptional
Cumulative amount refunded across all refunds on this payment.
data.transactionAmountnumberoptional
Original transaction amount. Equals totalRefundedAmount once fully refunded.
data.remainingRefundableAmountnumberoptional
Amount still refundable (transactionAmount − totalRefundedAmount).
data.paymentOrderIdstringoptional
Provider order identifier, when available.
data.microServiceTransactionIdstringoptional
Downstream refund transaction id, when available.

Required Headers#

Authorizationstringrequired
Bearer authentication. Format: Bearer base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.

Multiple Partial Refunds

You can issue multiple partial refunds on the same payment. Each refund reduces the remaining refundable balance. For example, on a 1500 DZD payment:

1. Refund 500 DZD → remaining refundable: 1000 DZD
2. Refund 300 DZD → remaining refundable: 700 DZD
3. Refund 700 DZD → remaining refundable: 0 DZD (fully refunded)
Full Refund (omit amount)
curl -X POST "https://api.payment.yassir.io/api/v1/payments/123e4567-e89b-12d3-a456-426614174000/refund" \
  -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 '{
    "description": "Customer requested full refund"
  }'
Partial Refund
curl -X POST "https://api.payment.yassir.io/api/v1/payments/123e4567-e89b-12d3-a456-426614174000/refund" \
  -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 '{
    "description": "Partial refund for item return",
    "amount": 500.00
  }'
200 OK — Full Refund (totalRefundedAmount == transactionAmount)
{
  "data": {
    "statusCode": 4,
    "status": "Transaction was refunded",
    "refundedAmount": 1500,
    "totalRefundedAmount": 1500,
    "transactionAmount": 1500,
    "remainingRefundableAmount": 0,
    "paymentOrderId": "ORDER_67890",
    "microServiceTransactionId": null,
    "errorMessage": {
      "internalErrorMessage": null,
      "providerErrorMessage": null
    }
  },
  "message": "Payment refunded successfully"
}
200 OK — Partial Refund (totalRefundedAmount < transactionAmount)
{
  "data": {
    "statusCode": 4,
    "status": "Transaction was refunded",
    "refundedAmount": 500,
    "totalRefundedAmount": 500,
    "transactionAmount": 1500,
    "remainingRefundableAmount": 1000,
    "paymentOrderId": "ORDER_67890",
    "microServiceTransactionId": null,
    "errorMessage": {
      "internalErrorMessage": null,
      "providerErrorMessage": null
    }
  },
  "message": "Payment refunded successfully"
}