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 and currency
  2. Proceed with a selected payment method
  3. Handle any redirects (3DS, OTP verification)
  4. Check the payment status

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.
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.com/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"
  }'

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 the selected payment method. Depending on the payment method, the response may indicate that additional user action is required (e.g., OTP verification, 3DS redirect).

POST/payments/intents/:id/proceed
Basic Auth
Process the payment using a selected payment method.

URL Parameters

idstringrequired
The paymentId returned from the Create Payment Intent endpoint.

Request Body

paymentMethodCodestringrequired
The payment method code from the List Payment Methods response. Example: WALLET_V2
secondaryPaymentMethodCodestringoptional
Optional secondary payment method for hybrid/split payments.
cardIdstringoptional
Required when using CREDIT_CARD payment method. The saved card identifier.

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.com/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 / 3DS)

When the payment method requires additional verification (OTP, 3DS, or bank redirect), 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.com/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 - 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 verification.

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

Refund Payment

Refund a completed payment, either fully or partially.

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 payment amount is refunded.
reasonstringoptional
Short reason code for the refund.

Example Request

Refund Payment
curl -X POST "https://api.payment.yassir.com/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 refund",
    "amount": 500.00
  }'
200 OK
{
  "data": {
    "id": "refund_xyz789",
    "paymentId": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 500.00,
    "status": "completed",
    "reason": "Customer requested refund"
  },
  "message": "payment refunded successfully"
}