Skip to main content

Create a Paymob payment intention for a shipment (by AWB)

POST
/api/v1/integrations/paymob/intention

Builds a Paymob payment intention for the shipment identified by awb to allow making online credit/debit card payments.

Behavior & Dynamic Logic

  • Dynamic Payment Source: The optional paymentSource parameter accepts whatsapp, buybuy, or website (defaulting to whatsapp). The server dynamically resolves this source to a corresponding Paymob Integration ID env var:
    • whatsapp → WHATSAPP_PAYMOB_ID
    • buybuy → BUYBUY_PAYMOB_ID
    • website → WEBSITE_PAYMOB_ID
  • Billing Data Resolution: Paymob requires complete billing data. The server automatically compiles this dynamically:
    • Consignee Path: If a consignee exists for the shipment, the server splits the consigneeName into first_name and last_name, uses addressText for street, and maps phone, city, state (governorate), and country.
    • Fallback Path: If no consignee is found, it falls back to the shipment's businessLocation details (using contact names, building/street information, and district/city data).
  • Payment URL & Iframe Configuration: Returns a direct payment URL redirecting the customer to the Paymob iframe checkout. The iframe ID is retrieved dynamically from the PAYMOB_IFRAME_ID environment variable (defaulting to 1002450).
  • Data Persistence: If a payment key record already exists for the AWB, the server regenerates the UUID-based merchantOrderId (sent to Paymob as special_reference) to prevent collisions; otherwise, it inserts a new pending row. The returned numeric Paymob order_id is persisted upon success.
  • Transaction Value: The optional amount is specified in EGP major units (e.g. 150.5) and is internally multiplied by 100 (cents) for Paymob. If omitted, the default cash amount on the shipment is used.
  • Authentication: Calls the Paymob API using PAYMOB_SECRET_KEY via bearer token authentication (Authorization: Token <key>).

Request​

Responses​

200 OK

Paymob intention created successfully.

400 Bad Request

Bad Request. Returned when:

  • request validation fails (e.g. missing awb, non-positive amount, invalid email);
  • no shipment exists for the provided AWB (Shipment not found for AWB <awb>);
  • no positive amount could be resolved from the body or shipment cash;
  • Paymob rejected the request (Paymob API error: <status> - <body>).
401 Unauthorized

Unauthorized - the provided API key is invalid or missing.

500 Internal Server Error

Internal Server Error - a required Paymob environment variable is missing or invalid (e.g. PAYMOB_SECRET_KEY, the resolved integration id, PAYMOB_EXPIRATION, PAYMOB_REDIRECTION_URL).