Intégrer

Paiement

Neuf profils de paiement, qui encaisse quoi, et à quel moment l'argent vous revient.

Choisir un profil

Le profil de paiement se décide à la création de l'envoi. Il fixe deux choses : qui paie le frais de livraison, et comment la marchandise est encaissée.

Code	Ce que ça veut dire	Payeur du frais	Encaissement
`CLIENT_PAYS_PREPAID`	Tout est payé au checkout.	Client	Prépayé
`FULL_COD`	Le client paie tout en espèces à la remise.	Client	À la livraison
`DEPOSIT_THEN_BALANCE`	Acompte digital, solde à la livraison.	Client	Acompte + solde
`SELLER_PAYS`	Le vendeur offre la livraison.	Vendeur	Prépayé
`FREE_DELIVERY_OVER`	Livraison offerte au-delà d'un montant.	Client	Prépayé
`SHARED_DELIVERY`	Frais partagé client / vendeur.	Partagé	Prépayé
`PLATFORM_PAYS_DELIVERY`	Rapidy offre la livraison (campagne).	Rapidy	Prépayé
`POSTPAID_BUSINESS_ACCOUNT`	Compte entreprise facturé en fin de période.	Vendeur	Postpayé
`EXTERNAL_PAYMENT_MANAGED_BY_TENANT`	Vous encaissez vous-même, hors Rapidy.	Vendeur	Externe

Sans profil explicite, l'envoi prend celui par défaut de votre organisation.

Paiement à la livraison

Créer un envoi encaissé à la livraison

# `order_amount_xof` = la valeur de la MARCHANDISE à encaisser.
# Sans lui, seul le frais de livraison serait collecté : la marchandise serait perdue.
curl -s -X POST "$RAPIDY_API_URL/v1/shipments" \
  -H "X-Api-Key: $RAPIDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qte_…",
    "external_order_id": "CMD-2026-42",
    "order_amount_xof": 10000,
    "payment_profile": { "code": "FULL_COD" }
  }'

const shipment = await rapidy.createShipment({
  quoteId: quote.id,
  externalOrderId: 'CMD-2026-42',
  // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
  orderAmountXof: 10_000,
  paymentProfile: { code: 'FULL_COD' },
});

console.log(shipment.payment.amountToCollectMinor); // marchandise + frais
console.log(shipment.payment.cashCollector);        // qui encaisse

shipment = rapidy.create_shipment(
    quote_id=quote["quote_id"],
    external_order_id="CMD-2026-42",
    # Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    order_amount_xof=10_000,
    payment_profile={"code": "FULL_COD"},
)

print(shipment["payment"]["amount_to_collect_minor"])  # marchandise + frais
print(shipment["payment"]["cash_collector"])           # qui encaisse

$shipment = $rapidy->createShipment([
    'quote_id'          => $quote['quote_id'],
    'external_order_id' => 'CMD-2026-42',
    // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    'order_amount_xof'  => 10000,
    'payment_profile'   => ['code' => 'FULL_COD'],
]);

shipment = rapidy.create_shipment(
  quote_id: quote['quote_id'],
  external_order_id: 'CMD-2026-42',
  # Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
  order_amount_xof: 10_000,
  payment_profile: { code: 'FULL_COD' }
)

shipment, err := client.CreateShipment(ctx, map[string]any{
    "quote_id":          quote["quote_id"],
    "external_order_id": "CMD-2026-42",
    // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    "order_amount_xof":  10000,
    "payment_profile":   map[string]any{"code": "FULL_COD"},
})

Map<String, Object> shipment = rapidy.createShipment(Map.of(
    "quote_id", quote.get("quote_id"),
    "external_order_id", "CMD-2026-42",
    // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    "order_amount_xof", 10000,
    "payment_profile", Map.of("code", "FULL_COD")));

var shipment = await rapidy.CreateShipmentAsync(new Dictionary<string, object>
{
    ["quote_id"] = quote["quote_id"]!,
    ["external_order_id"] = "CMD-2026-42",
    // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    ["order_amount_xof"] = 10000,
    ["payment_profile"] = new Dictionary<string, object> { ["code"] = "FULL_COD" },
});

final shipment = await rapidy.createShipment(
  CreateShipmentRequest.fromQuote(
    quoteId: quote.id,
    externalOrderId: 'CMD-2026-42',
    // Valeur de la MARCHANDISE. Sans elle, seul le frais de livraison est collecté.
    orderAmountXof: 10000,
    paymentProfile: const PaymentProfile(code: 'FULL_COD'),
  ),
);

order_amount_xof n'est pas facultatif sur un COD. Sans lui, seul le frais de livraison est collecté : le livreur remet le colis et repart sans la valeur de la marchandise. L'erreur ne se voit qu'à la réconciliation, quand le montant attendu ne tombe pas.

La réponse porte payment.amount_to_collect_minor (marchandise + frais) et payment.cash_collector : lisez-les plutôt que de recalculer de votre côté.

Qui a le droit d'encaisser des espèces

Tout le monde ne peut pas manipuler du cash. C'est une règle métier, pas un réglage.

Les entreprises partenaires certifiées collectent les espèces pour le compte de leurs clients.
Un livreur indépendant ne peut encaisser que s'il est certifié et si son compte couvre le montant à collecter — sinon la plateforme avancerait un risque qu'elle n'a pas accepté.
Quand aucune des deux conditions n'est remplie, Rapidy bascule sur un lien de paiement présenté au destinataire à la confirmation de réception. Le colis part quand même ; c'est le mode d'encaissement qui change.

Votre code n'a pas à décider : la réponse de createShipment vous dit le mode retenu. Affichez-le, ne le devinez pas.

L'argent qui revient

La livraison ne vous crédite pas. Tant que l'espèce n'a pas été physiquement remise, elle est dans la sacoche du livreur. La réconciliation se déclenche sur la remise, pas sur la livraison — et votre règlement s'ouvre à ce moment-là.

L'enchaînement :

Livré — l'encaissement est constaté, la course est terminée.
Remis — le livreur dépose l'espèce ; c'est ce signal qui déclenche la suite.
Réconcilié — la réserve de risque du livreur est libérée, votre règlement est crédité de la valeur de la marchandise.
Versé — le règlement clôturé est décaissé vers votre compte.

Chaque étape émet un événement : abonnez-vous plutôt que d'interroger.

Gels de retrait

Trois situations retiennent temporairement un solde. Elles ne concernent pas votre intégration directement, mais expliquent ce que vos partenaires voient :

une mission en cours gèle la part correspondante ;
un litige ouvert gèle le règlement de l'envoi concerné jusqu'à l'arbitrage ;
un solde sous le minimum impose un délai avant nouveau retrait.

Un gel n'est pas une sanction : c'est ce qui permet de rembourser sans avoir à réclamer.