YassirDocs

Customers

Register customers before creating payment intents

Before creating a payment intent, you must register the customer with Yassir Payment. The customer's phone number is used as the userId when creating payment intents.

Prerequisite

Customers must be registered before creating payment intents. If you pass a userId (phone number) that doesn't exist as a customer, the payment intent will fail.

Create Customer#

Registers a new customer with the payment gateway. If the customer already exists (same phone number), a 409 Conflict is returned.

POST/api/v1/customers
Bearer Token
Register a new customer by phone number.

Request Body#

namestringrequired
The customer's display name.
phonestringrequired
The customer's phone number in international format (e.g., +213555123456). This will be used as the userId when creating payment intents.
emailstringoptional
The customer's email address (optional).
isActivebooleanoptional
Whether the customer should be active. Defaults to true.

Idempotent Registration

If a customer with the same phone number already exists, the API returns a 409 Conflict. Your integration should handle this gracefully — simply continue to creating the payment intent. See the example below.
Create Customer
curl -X POST https://api.payment.yassir.io/api/v1/customers \
  -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 '{
    "name": "John Doe",
    "phone": "+213555123456",
    "isActive": true
  }'
201 Created
{
  "code": 201,
  "status": "success",
  "message": "Successfully created customer",
  "data": {
    "name": "John Doe",
    "email": null,
    "phone": "+213555123456"
  }
}

Integration Pattern#

A common pattern is to "ensure" the customer exists before every checkout. This is safe because the API returns a 409 if the customer is already registered:

Ensure Customer Exists Pattern
async function ensureCustomerExists(phone) {
  try {
    await gateway.post('/customers', {
      name: phone,
      phone,
      isActive: true,
    });
    console.log('Created customer:', phone);
  } catch (err) {
    if (err.response?.status === 409) {
      // Customer already exists — safe to continue
      console.log('Customer already exists:', phone);
    } else {
      throw err;
    }
  }
}

// Before creating a payment intent:
await ensureCustomerExists(userPhone);
const intent = await gateway.post('/payments/intents', {
  actionId: 'order_12345',
  amount: 1500.00,
  actionCurrencyCode: 'DZD',
  actionCountryCode: 'DZA',
  userId: userPhone, // Must match the registered phone number
});

Get Customer#

Retrieve a customer by their ID.

GET/api/v1/customers/:id
Bearer Token
Retrieve customer details by ID.

Search Customer by Phone#

Look up a customer by their phone number.

GET/api/v1/customers/search/:phone
Bearer Token
Search for a customer by phone number.
Search Customer by Phone
curl https://api.payment.yassir.io/api/v1/customers/search/+213555123456 \
  -H "Authorization: Bearer $(echo -n 'your_client_id:your_client_secret' | base64)" \
  -H "x-platform: API" \
  -H "x-service: YOUR_SERVICE"

Update Customer#

Update an existing customer's details.

PUT/api/v1/customers/:id
Bearer Token
Update customer details.
namestringoptional
Updated display name.
emailstringoptional
Updated email address.
phonestringoptional
Updated phone number in international format.
isActivebooleanoptional
Set to false to deactivate the customer.