Y

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 Wallet 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/payments/intents
Basic Auth
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
Your unique identifier for the user making the payment.
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
Basic authentication. Format: Basic 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.

Example Request

Create Payment Intent
curl -X POST "https://api.payment.yassir.io/payments/intents?countryCode=DZA" \
  -H "Authorization: Basic $(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"
  }'

Response

201 Created
{
  "data": {
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "clientSecret": "pa_abc123_secret_xyz789",
    "status": "pending",
    "amount": 1500.00,
    "currency": "DZD"
  },
  "message": "payment initiated successfully"
}
data.paymentIdstringrequired
Unique payment identifier. Use this in all subsequent calls.
data.clientSecretstringrequired
Payment-scoped secret for this specific payment.
data.statusstringrequired
Current payment status. Will be pending after creation.
data.amountnumberrequired
The payment amount.
data.currencystringrequired
The payment currency code.

Proceed with Payment

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

POST/payments/intents/:id/proceed
Basic Auth
Process the payment using Yassir Wallet.

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 Wallet.

Required Headers

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

Example Request

Proceed with Payment
curl -X POST "https://api.payment.yassir.io/payments/intents/123e4567-e89b-12d3-a456-426614174000/proceed" \
  -H "Authorization: Basic $(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-token: user_token_here" \
  -d '{
    "paymentMethodCode": "WALLET_V2"
  }'

Response - Direct Success

When the payment completes immediately (e.g., wallet with sufficient balance and no OTP):

200 OK - Success
{
  "data": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "The amount was deposited successfully",
    "statusCode": 2,
    "require3DS": false,
    "metadata": {}
  },
  "message": "payment proceeded successfully"
}

Response - Requires Action (OTP)

When the wallet requires OTP verification, the response includes a payUrl that the user must be redirected to:

200 OK - Requires Action
{
  "data": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Pending 3DS Verification",
    "statusCode": 12,
    "require3DS": true,
    "metadata": {
      "payUrl": "https://payment-otp.yassir.io/otp/verify?requestId=txn_abc123&phone=213555123456&amount=1500&currency=DZD&paymentMethod=WALLET_V2"
    }
  },
  "message": "payment proceeded successfully"
}

Handling Redirects

When require3DS is true, you must redirect the user to the payUrl. Append a returnUrl query parameter so the user is redirected back to your app after completing verification. Example:payUrl + &returnUrl=https://yourapp.com/payment-success?paymentId=...

Response - Pre-Authorized

When using captureMethod: "RESERVATION", a successful proceed returns a pre-authorized status. The funds are reserved but not yet captured.

200 OK - Pre-Authorized
{
  "data": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Pre-authorized",
    "statusCode": 13,
    "require3DS": false,
    "metadata": {}
  },
  "message": "payment proceeded successfully"
}

Response - Rejected

When the payment is rejected by the provider (e.g., insufficient balance):

200 OK - Rejected
{
  "data": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Transaction was rejected",
    "statusCode": 3,
    "require3DS": false,
    "metadata": {}
  },
  "message": "payment proceeded successfully"
}

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.

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/payments/intents/:id/check
Basic Auth
Check the current status of a payment intent.

URL Parameters

idstringrequired
The paymentId to check.

Required Headers

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

Example Request

Check Payment Status
curl -X GET "https://api.payment.yassir.io/payments/intents/123e4567-e89b-12d3-a456-426614174000/check" \
  -H "Authorization: Basic $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-platform: API" \
  -H "x-service: YOUR_SERVICE" \
  -H "x-client-token: user_token_here"

Response

200 OK
{
  "data": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "The amount was deposited successfully",
    "statusCode": 2,
    "amount": 1500.00,
    "currency": "DZD",
    "paymentMethodCode": "WALLET_V2"
  },
  "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/payments/intents/:id/capture
Basic Auth
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
Basic authentication. Format: Basic base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.

Example Request

Capture Payment
# Capture a partial amount (e.g., reserved 5000, capture 4500)
curl -X POST "https://api.payment.yassir.io/payments/intents/123e4567-e89b-12d3-a456-426614174000/capture" \
  -H "Authorization: Basic $(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": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "The amount was deposited successfully",
    "statusCode": 2
  },
  "message": "payment captured successfully"
}

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.

Release Payment

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

POST/payments/intents/:id/release
Basic Auth
Release a pre-authorized payment without capturing.

URL Parameters

idstringrequired
The paymentId of the pre-authorized payment.

Required Headers

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

Example Request

Release Payment
curl -X POST "https://api.payment.yassir.io/payments/intents/123e4567-e89b-12d3-a456-426614174000/release" \
  -H "Authorization: Basic $(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": {
    "id": "txn_abc123",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Reversed",
    "statusCode": 10
  },
  "message": "payment released successfully"
}

Refund Payment

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

POST/payments/:paymentId/refund
Basic Auth
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
Basic authentication. Format: Basic base64(client_id:client_secret)
x-platformstringrequired
The platform making the request.
Allowed values:
APIWEBANDROIDIOS
x-servicestringrequired
Your service identifier.

Example: Full Refund

Full Refund (omit amount)
curl -X POST "https://api.payment.yassir.io/payments/123e4567-e89b-12d3-a456-426614174000/refund" \
  -H "Authorization: Basic $(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"
  }'

Example: Partial Refund

Partial Refund
curl -X POST "https://api.payment.yassir.io/payments/123e4567-e89b-12d3-a456-426614174000/refund" \
  -H "Authorization: Basic $(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
{
  "data": {
    "id": "refund_xyz789",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 500.00,
    "status": "completed",
    "reason": "Partial refund for item return"
  },
  "message": "payment refunded successfully"
}

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)