Order creation

Coming soon. This webhook is not available yet.

TapiPay notifies you with this webhook when a payment order is created or when the creation of the charge fails. It only comes with three POST /v2/debts/orders responses: 201, 422 ORDER_NOT_CREATED and 500. With any other one (for example, an invalid field, a contact that does not exist or a key already used), there is no webhook: the reason only reaches you in the response. On a 500, this webhook may or may not arrive. If ORDER_CREATION_FAILED arrives with PROVIDER_UNAVAILABLE, it does not mean nothing was charged: retry with the same externalRequestId, as described in Retries and idempotency.

`type`	`orderStatus`	When it arrives
`ORDER_CREATION_SUCCESS`	`PROCESSING`	The order was created.
`ORDER_CREATION_FAILED`	`FAILED`	The order creation failed. The reason comes in `creationError`.

It is part of the order and payment method webhooks: it shares the endpoint, the security and the contract with them. Its idempotency key is id.

Creation and charge are separate notices

ORDER_CREATION_SUCCESS reports that the order was created, not that it was charged. The result of the charge reaches you later, with the order payment. You can receive ORDER_CREATION_FAILED and then ORDER_PAYMENT_CONFIRMED for the same order, if the bank ended up processing the charge. In that case, take the charge as final: the money came in.

The payload

Field	Type	Present	Description
`type`	String	Always	`ORDER_CREATION_SUCCESS` or `ORDER_CREATION_FAILED`. Use it to route.
`hash`	String \| null	Always	Verification hash. `null` if you do not have a public key configured. See Webhook security.
`id`	String (uuid)	Always	Unique identifier of the notification. If it reaches you again, it carries the same `id`. Use it as the idempotency key.
`orderId`	String (uuid)	Variable	The order’s `orderId`. Always in `ORDER_CREATION_SUCCESS`. In `ORDER_CREATION_FAILED` only if the order got to be created.
`externalOrderId`	String	Always	Your identifier for the order, the `externalRequestId`.
`orderStatus`	String	Always	`PROCESSING` in `ORDER_CREATION_SUCCESS`, `FAILED` in `ORDER_CREATION_FAILED`.
`companyCode`	String	Always	Code of the order’s company.
`externalClientId`	String	Always	Your identifier for the user.
`amount`	Number	Always	Order amount, in pesos with up to 2 decimals.
`currency`	String	Always	Currency, in ISO 4217. For now `MXN`.
`paymentProcessor`	String	Always	For now `BANK_ACCOUNT`.
`paymentMethod`	Object	Variable	The order’s payment method: `{ type, externalPaymentMethodId }`. Always in `ORDER_CREATION_SUCCESS`. In `ORDER_CREATION_FAILED` it may not come, for example with `PAYMENT_METHOD_NOT_SUPPORTED`. It never carries the account number or the CLABE.
`creationError`	Object	Only `ORDER_CREATION_FAILED`	Reason: `{ code, message }`. See Reasons.
`additionalData`	Object	Always	For now it always arrives empty (`{}`).
`createdAt`	String	Only `ORDER_CREATION_SUCCESS`	When the order was created, in ISO 8601 UTC.
`failedAt`	String	Only `ORDER_CREATION_FAILED`	When the creation failed, in ISO 8601 UTC.

If orderId or paymentMethod do not come, the key is not there: they do not arrive as null or empty. Check that they exist before reading them.

Reasons

creationError.code is a TapiPay code, not the bank’s. message comes in English and is meant for your logs, not for showing to the user.

`code`	`message`	What it means
`PAYMENT_METHOD_REQUIRED`	The order requires a payment method	The order needs a payment method.
`PAYMENT_METHOD_NOT_SUPPORTED`	The payment method is not supported for this order	The payment method cannot be used for this kind of order.
`PAYMENT_METHOD_INACTIVE`	The payment method is not active	The bank reported that the account is not active. Ask the user to register another one.
`ORDER_REJECTED`	The order was rejected by the payment provider	The bank declined the charge.
`PROVIDER_UNAVAILABLE`	The payment provider could not confirm the order	The bank did not confirm in time. The order can still be charged.
`INTERNAL_ERROR`	The order could not be created	A TapiPay failure, not attributable to your request.
`INVALID_ORDER_REQUEST`	The order request was rejected	The order does not meet a rule. It was not created.

Treat the list of codes as open: new codes can be added. If you receive one you do not know, treat it as a creation failure with no specific action.

Examples

An order that is created, one that is created but fails, and one whose creation failed before the order existed (without orderId). The examples correspond to an integration without a public key, which is why hash comes as null.

{
  "type": "ORDER_CREATION_SUCCESS",
  "hash": null,
  "id": "3c9e7a14-6b2d-5f80-a1c3-9d4e8b2f6a07",
  "orderId": "6f1c2b9e-4d3a-4b8e-9a71-2c5d8e0f1a23",
  "externalOrderId": "CARGO-2026-00042",
  "orderStatus": "PROCESSING",
  "companyCode": "MX-S-12345",
  "externalClientId": "CLI-00042",
  "amount": 350.00,
  "currency": "MXN",
  "paymentProcessor": "BANK_ACCOUNT",
  "paymentMethod": { "type": "BANK_ACCOUNT", "externalPaymentMethodId": "b7e4a0c2-9f13-4e6d-8a25-71c3d9e0b4f8" },
  "additionalData": {},
  "createdAt": "2026-10-23T15:00:04.000Z"
}

{
  "type": "ORDER_CREATION_FAILED",
  "hash": null,
  "id": "d17b4e92-0a6c-5e31-8f2b-6c3a9e1d7b40",
  "orderId": "4e7b1a90-2c6d-4f3e-8a15-6b9d0c2e7f48",
  "externalOrderId": "CARGO-2026-00043",
  "orderStatus": "FAILED",
  "companyCode": "MX-S-12345",
  "externalClientId": "CLI-00043",
  "amount": 980.00,
  "currency": "MXN",
  "paymentProcessor": "BANK_ACCOUNT",
  "paymentMethod": { "type": "BANK_ACCOUNT", "externalPaymentMethodId": "7d2c9e14-5a3b-4f86-b1e0-9c4a8f6d2b53" },
  "creationError": { "code": "PAYMENT_METHOD_INACTIVE", "message": "The payment method is not active" },
  "additionalData": {},
  "failedAt": "2026-10-23T15:05:12.000Z"
}

{
  "type": "ORDER_CREATION_FAILED",
  "hash": null,
  "id": "8a5f2c63-e91d-5b47-9c06-1f8d3a7e4b29",
  "externalOrderId": "CARGO-2026-00044",
  "orderStatus": "FAILED",
  "companyCode": "MX-S-12345",
  "externalClientId": "CLI-00044",
  "amount": 120.00,
  "currency": "MXN",
  "paymentProcessor": "BANK_ACCOUNT",
  "paymentMethod": { "type": "BANK_ACCOUNT", "externalPaymentMethodId": "3f8a6d21-7c4e-4b95-a0d2-5e9b1c7f4a36" },
  "creationError": { "code": "INVALID_ORDER_REQUEST", "message": "The order request was rejected" },
  "additionalData": {},
  "failedAt": "2026-10-23T15:07:30.000Z"
}

Recommendations

Process each notification only once. The same notification can arrive more than once, always with the same id. Store the processed id values in persistent storage.
Correlate by externalOrderId. It is the only identifier that always comes: orderId is missing if the order did not get to be created.
Do not assume an arrival order between this notice and the order payment ones.
Ignore fields you do not know: new fields can be added.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Creation and charge are separate notices

The payload

Reasons

Examples

Recommendations

​Creation and charge are separate notices

​The payload

​Reasons

​Examples

​Recommendations

Creation and charge are separate notices

The payload

Reasons

Examples

Recommendations