> For the complete documentation index, see [llms.txt](https://docs.intram.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.intram.org/merchant-api-v1/payment-requests.md).

# Demandes de paiement

Crée une demande de paiement adressée à un client. Le worker initialise une Transaction + une Invoice, puis renvoie l'URL du gateway de paiement Intram à présenter au client.

## Flow complet

```
1. POST /payment-requests         → 202 + operation_id
2. Worker crée Transaction PENDING
3. Webhook payment_request.created → result.gateway_url disponible
4. Tu redirigeas le client vers gateway_url (ou tu lui envoies par email/SMS)
5. Le client paie via le gateway
6. Webhook payment_request.paid|pending|failed selon le résultat
```

## Requête

```http
POST /v1/payment-requests
X-Api-Key: …
X-Timestamp: …
X-Signature: …
Idempotency-Key: pr-order-4521-attempt-1
Content-Type: application/json
```

### Body

```json
{
  "invoice": {
    "amount": 12000,
    "currency": "XOF",
    "description": "Commande #4521",
    "customer": {
      "email": "client@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "phone": "22961234567"
    }
  },
  "payment_method": {
    "code": "MTN_BENIN_229",
    "country_code": "BJ",
    "msisdn": "22961234567"
  },
  "return_urls": {
    "success": "https://shop.example.com/ok",
    "cancel":  "https://shop.example.com/no"
  },
  "webhook_data": { "order_id": "4521" }
}
```

### Validation

| Champ                    | Obligatoire | Règles                                            |
| ------------------------ | :---------: | ------------------------------------------------- |
| `invoice.amount`         |      ✓      | Number > 0, dans les limites min/max de la devise |
| `invoice.currency`       |      ✓      | Code ISO 3 lettres                                |
| `invoice.description`    |  optionnel  | Max 500 chars                                     |
| `invoice.customer`       |      ✓      | Object                                            |
| `invoice.customer.email` |  optionnel  | Email valide                                      |
| `invoice.customer.phone` |  optionnel  | String                                            |
| `payment_method`         |  optionnel  | Suggère un moyen de paiement par défaut au client |
| `return_urls.success`    |  optionnel  | URL où rediriger après succès                     |
| `return_urls.cancel`     |  optionnel  | URL où rediriger après annulation                 |
| `webhook_data`           |  optionnel  | Object libre transmis dans les webhooks           |

## Réponse `202 Accepted`

```json
{
  "error": false,
  "http_status": 202,
  "data": {
    "operation_id": "op_4d2a…",
    "type": "payment_request",
    "status": "queued",
    "env": "live",
    "date": "2026-05-20T10:30:00.000Z"
  }
}
```

## Résultat final (op.result après `payment_request.created`)

```json
{
  "transaction_reference": "AB12CD34EF",
  "status": "pending",
  "amount": 12000,
  "currency": "XOF",
  "gateway_url":  "https://gateway.intram.org/AB12CD34EF",
  "payment_url":  "https://gateway.intram.org/AB12CD34EF",
  "receipt_url":  "https://gateway.intram.org/AB12CD34EF",
  "qr_code": "data:image/png;base64,iVBOR…"
}
```

| Champ         | Description                                       |
| ------------- | ------------------------------------------------- |
| `gateway_url` | URL canonique du checkout — à présenter au client |
| `payment_url` | Alias de `gateway_url` (compat)                   |
| `receipt_url` | URL de la facture imprimable une fois settled     |
| `qr_code`     | Data-URL PNG du QR pointant vers `gateway_url`    |

## Événements webhook

| Événement                 | Quand                                                       |
| ------------------------- | ----------------------------------------------------------- |
| `payment_request.created` | Worker a créé la transaction → `gateway_url` disponible     |
| `payment_request.paid`    | Le client a payé avec succès                                |
| `payment_request.pending` | Le client a initié mais le provider n'a pas encore confirmé |
| `payment_request.failed`  | Échec côté client / provider / timeout                      |

## Cas d'usage typiques

### E-commerce — checkout immédiat

```javascript
// 1. Ton client clique "Payer"
const { data: op } = await intram.paymentRequests.create({...});

// 2. Tu attends le webhook payment_request.created (ou polles ~1s)
const final = await waitForOperation(op.data.operation_id);

// 3. Tu rediriges
res.redirect(final.result.gateway_url);
```

### Facture par email

```javascript
const final = await waitForOperation(op.data.operation_id);
await sendEmail(customerEmail, {
  subject: 'Votre facture',
  body: `Payer ici : ${final.result.gateway_url}`,
});
```

### QR à scanner en boutique

```javascript
const final = await waitForOperation(op.data.operation_id);
display(final.result.qr_code);   // affichage sur écran caisse / impression
```

## Erreurs

| Code                                    | Cas                               |
| --------------------------------------- | --------------------------------- |
| `validation_error`                      | Body invalide                     |
| `unknown_currency`                      | Devise non supportée              |
| `amount_too_small` / `amount_too_large` | Hors des limites min/max          |
| `missing_invoice`                       | Le body n'a pas de bloc `invoice` |

## Voir aussi

* [Statut transaction](/merchant-api-v1/transactions.md) — lire le statut d'une transaction créée par cet endpoint
* [Webhooks](/merchant-api-v1/webhooks.md) — recevoir le résultat final en push


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.intram.org/merchant-api-v1/payment-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.