Webhooks

Partners configure a webhook URL via API. Deliveries cover all of your merchants. Event types and fulfillment rules match the merchant Webhooks guide, with partner fields on the envelope.

Configure

Environment comes from your Partner API key (pt_test_ → test, pt_live_ → live).

curl -X PUT http://api.localhost:4000/v1/partner/webhook \
  -H "Authorization: Bearer pt_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example/webhooks/orqpay",
    "secret": "your-signing-secret-16+",
    "enabled": true
  }'

• Secret required on first create (16–255 characters)
• Omit secret on later updates to keep the existing one

curl http://api.localhost:4000/v1/partner/webhook \
  -H "Authorization: Bearer pt_test_..."

Events

Same invoice.* catalog as merchants. Fulfill only on invoice.paid.

Example envelope:

{
  "id": "<invoiceId>-<sequence>",
  "type": "invoice.paid",
  "createdAt": "2026-07-04T12:00:00Z",
  "environment": "test",
  "partnerId": "uuid",
  "data": {
    "invoiceId": "uuid",
    "merchantId": "uuid",
    "externalTenantId": "your-tenant-id",
    "status": "PAID",
    "amount": "10",
    "amountReceived": "10",
    "token": "USDC",
    "sequence": 3
  }
}

Process idempotently on envelope id.

Verify signatures

Same scheme as merchant webhooks:

X-Coinpay-Signature: t=<unix_seconds>,v1=<hmac_hex>

HMAC-SHA256 over {timestamp}.{rawBody} with your webhook secret. Reject timestamps older than 5 minutes. Always verify the raw body.

Full example: Merchant webhooks — Verify signatures.

Deliveries

Inspect and resend if needed:

• GET /v1/partner/webhook/deliveries
• GET /v1/partner/webhook/deliveries/{id}
• POST /v1/partner/webhook/deliveries/{id}/resend

Related

• Merchant webhooks
• Invoice lifecycle
• API — put webhook