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.

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

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.

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.
x-client-secretstringrequired
The clientSecret returned from the Create Payment Intent endpoint. Format: pa_{id}_secret_{hex}
x-country-codestringoptional
ISO 3166-1 alpha-3 country code. Example: DZA
x-localestringoptional
Locale for localized responses. Example: en_US

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.

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
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-client-secret: pa_123e4567_secret_a1b2c3d4e5f6" \
  -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"
}

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
Bearer authentication. Format: Bearer base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.
x-client-secretstringrequired
The clientSecret returned from the Create Payment Intent endpoint.

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
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" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"
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"
}

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.

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 (statusCode: 4)
{
  "data": {
    "statusCode": 4,
    "status": "Transaction was refunded",
    "paymentOrderId": "ORDER_67890",
    "microServiceTransactionId": null,
    "errorMessage": {
      "internalErrorMessage": null,
      "providerErrorMessage": null
    }
  },
  "message": "Payment refunded successfully"
}
200 OK — Partial Refund (statusCode: 16)
{
  "data": {
    "statusCode": 16,
    "status": "Transaction was partially refunded",
    "paymentOrderId": "ORDER_67890",
    "microServiceTransactionId": null,
    "errorMessage": {
      "internalErrorMessage": null,
      "providerErrorMessage": null
    }
  },
  "message": "Payment refunded successfully"
}