ribbonPay Direct/API Integration Guide

This guide is the published Direct/API documentation (also served at /docs). The interactive OpenAPI reference is at /docs/api; the machine-readable spec is at /openapi.json. Credentials are provisioned by ribbonPay ops — there is no self-serve signup.

This guide is for merchants whose checkout or order-management system connects to ribbonPay over HTTPS — custom carts, Adobe Commerce (Magento), BigCommerce custom flows, headless storefronts, and any platform where your developers call our REST API directly.

Not for Shopify. Shopify merchants install the ribbonPay app; orders arrive via Shopify webhooks and decisions are written back to Shopify automatically. This guide covers the Direct/API path only (the same API the WooCommerce plugin uses under the hood).

1. Integration model

ribbonPay is a server-to-server integration. Your backend calls ribbonPay when an order is placed, holds fulfillment until ribbonPay approves it, and acts on the decision we return.

1. Your backend POSTs the order to /api/v1/orders with a Bearer API key.
2. ribbonPay returns 200 with decision PENDING, SHIP, or CANCEL.
3. Hold capture and fulfillment until you receive SHIP.
4. Optionally PATCH late gateway data (AVS, CVV, BIN).
5. Analysts review PENDING orders.
6. ribbonPay POSTs a signed webhook with the final SHIP or CANCEL.
7. On SHIP, fulfill; on CANCEL, void or refund.

When to call ribbonPay

Call POST /api/v1/orders immediately after payment authorization succeeds and before you capture funds or ship goods. Your integration must:

1. Authorize payment with your gateway (do not capture yet, unless your business model requires otherwise).
2. Submit the order to ribbonPay and read the synchronous response.
3. Hold fulfillment until you receive an explicit SHIP decision (synchronous response or later webhook).
4. Act on the final decision:
   • SHIP — capture payment (if not already captured) and fulfill the order.
   • CANCEL — void authorization, refund, or cancel the order per your gateway workflow.
   • PENDING — keep the order on hold; a human analyst will review it. The final decision arrives via signed webhook (see §7).

Training period (new merchants)

During the initial onboarding period (~90 days), ribbonPay routes orders to human review by default, so the synchronous API response will be PENDING for most orders. Automatic decisions are allowed during training: as our analysts identify reliable signals for your store, they may introduce auto-approve or auto-cancel rules, so your integration must handle a synchronous SHIP or CANCEL from day one. You must also implement the webhook receiver — that is how you receive SHIP and CANCEL after analyst review.

2. What ribbonPay provides / what we need from you

ribbonPay provides (integration packet)

We need from you

3. Authentication

Every API request must include your API key in the Authorization header:

Authorization: Bearer rp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Authentication errors (401)

All responses include an X-Request-Id header — include it when contacting ribbonPay support.

4. Submit an order — POST /api/v1/orders

POST /api/v1/orders

Creates (or idempotently returns) an order and runs enrichment, scoring, and rules. Returns a synchronous decision when data is complete.

Required fields

Address shape (both billing and shipping):

Line item shape:

Optional fields (recommended for accurate scoring)

Send everything your gateway and cart can provide. More payment and customer context improves review quality.

Unknown fields are rejected (400 invalid_request). Send only fields listed above.

Minimal request example

{
  "external_order_id": "ORD-10042",
  "customer_email": "buyer@example.com",
  "billing_address": {
    "street": "1 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "shipping_address": {
    "street": "1 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "ip_address": "203.0.113.45",
  "line_items": [
    { "sku": "WIDGET-01", "quantity": 1, "price": 49.99 }
  ],
  "order_total": 49.99
}

Full request example (with payment data)

{
  "external_order_id": "ORD-10042",
  "customer_email": "buyer@example.com",
  "customer_name": "Jane Buyer",
  "customer_phone": "+15125550100",
  "billing_address": {
    "street": "1 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "shipping_address": {
    "street": "99 Oak Ave",
    "city": "Dallas",
    "state": "TX",
    "zip": "75201",
    "country": "US"
  },
  "ip_address": "203.0.113.45",
  "line_items": [
    {
      "sku": "WIDGET-01",
      "quantity": 2,
      "price": 24.99,
      "description": "Premium widget"
    }
  ],
  "order_total": 54.98,
  "order_subtotal": 49.98,
  "order_tax": 5.00,
  "currency": "USD",
  "order_placed_at": "2026-06-29T15:30:00Z",
  "gateway": "authorize_net",
  "payment_method": "credit_card",
  "payment_status": "authorized",
  "avs_code": "Y",
  "cvv_code": "M",
  "card_bin": "411111",
  "card_last4": "1111",
  "card_brand": "visa",
  "card_exp_month": 12,
  "card_exp_year": 2028,
  "customer_order_count": 3,
  "customer_total_spend": 450.00,
  "ship_method": "UPS Ground"
}

Success response (200)

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "PENDING",
  "reason_code": "no_decision_rule",
  "timestamp": "2026-06-29T15:30:01.123Z"
}

Awaiting data (awaiting_fields)

If your merchant account has a decision_required_fields contract and the payload is missing those fields, the order is stored but not scored yet:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "PENDING",
  "reason_code": "awaiting_data",
  "timestamp": "2026-06-29T15:30:01.123Z",
  "awaiting_fields": ["avs_code", "card_bin"]
}

Send the missing fields via PATCH /api/v1/orders/{external_order_id} (§5). When complete, ribbonPay runs enrichment and decision automatically.

curl example

curl -X POST "https://<your-ribbonpay-host>/api/v1/orders" \
  -H "Authorization: Bearer rp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d @order.json

5. Backfill / update — PATCH /api/v1/orders/{external_order_id}

PATCH /api/v1/orders/{external_order_id}

Send only the fields you want to add or correct. Use this when gateway data (AVS, CVV, BIN) arrives after the initial order submission — the same pattern used by the WooCommerce + Authorize.net integration.

Rules

Updatable fields

All optional fields from §4 except external_order_id and customer_email (includes device_session_id for late collector correlation).

Common PATCH payloads:

{
  "avs_code": "Y",
  "cvv_code": "M",
  "card_bin": "411111",
  "card_last4": "1111",
  "card_brand": "visa",
  "payment_status": "authorized"
}

Response shapes (200)

The response includes updated_fields (list of field names applied) and varies by outcome:

Still awaiting required fields:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "awaiting_data",
  "awaiting_fields": ["card_bin"],
  "updated_fields": ["avs_code", "cvv_code"]
}

Data merged, order not yet complete for decision (no contract transition):

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "PENDING",
  "reason_code": "awaiting_data",
  "risk_score": 0,
  "timestamp": "2026-06-29T15:30:05.000Z",
  "updated_fields": ["gateway"]
}

Completeness reached — decision run:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "PENDING",
  "reason_code": "no_decision_rule",
  "risk_score": 42,
  "timestamp": "2026-06-29T15:30:05.000Z",
  "updated_fields": ["avs_code", "card_bin"]
}

Order already decided (SHIP or CANCEL) — fields merged, decision unchanged:

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "SHIP",
  "reason_code": "analyst_ship",
  "risk_score": 15,
  "timestamp": "2026-06-29T16:00:00.000Z",
  "updated_fields": ["ship_method"],
  "status": "merged_post_decision"
}

Payment error detected (via payment_status):

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "payment_error",
  "reason_code": "payment_error",
  "timestamp": "2026-06-29T15:30:05.000Z",
  "updated_fields": ["payment_status"]
}

Merchant cancelled (via order_status or payment_status):

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "merchant_cancelled",
  "reason_code": "merchant_cancelled",
  "timestamp": "2026-06-29T15:30:05.000Z",
  "updated_fields": ["order_status"]
}

Errors

6. Decision handling

Where decisions arrive

Webhooks are sent only for SHIP and CANCEL — never for PENDING.

If the synchronous response is PENDING, you must implement the webhook receiver to get the final outcome.

Common reason_code values

7. Receiving decisions (webhook)

ribbonPay POSTs to the webhook_url configured on your merchant account when an order receives a final SHIP or CANCEL decision.

Request from ribbonPay

POST https://your-site.com/ribbonpay/webhook
Content-Type: application/json
X-Ribbonpay-Event: order.decision
X-Ribbonpay-Signature: <hex-encoded HMAC-SHA256>
X-Ribbonpay-Signature-Previous: <hex>   # only during the 7-day window after secret rotation
X-Ribbonpay-Delivery-Id: <uuid>   # present on deliveries created after webhook_deliveries rollout

Body:

{
  "event": "order.decision",
  "event_id": "a1b2c3d4e5f6789012345678abcdef01",
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_order_id": "ORD-10042",
  "decision": "SHIP",
  "reason_code": "analyst_ship",
  "timestamp": "2026-06-29T16:45:00.000Z"
}

At-least-once delivery: queue delivery can deliver the same event more than once. Deduplicate on event_id (preferred) before applying the decision. The optional X-Ribbonpay-Delivery-Id header identifies a specific QStash delivery attempt/message for tracing — do not use it as the business dedup key.

Signature verification

1. Read the raw request body as a string (before JSON parsing).
2. Compute HMAC-SHA256 of that raw body using your webhook signing secret.
3. Compare the result (hex-encoded, lowercase) to the X-Ribbonpay-Signature header using a constant-time comparison.
4. During secret rotation, also accept a match against X-Ribbonpay-Signature-Previous (present for 7 days after ribbonPay rotates your signing secret). Accept the request if either signature verifies.
5. Reject the request if neither signature matches.

The request body is sent as canonical JSON (object keys sorted alphabetically at every nesting level). Verify against the exact bytes received — do not re-serialize parsed JSON unless your serializer produces identical output.

Node.js example

import { createHmac, timingSafeEqual } from 'crypto'

function verifyRibbonpayWebhook(rawBody, signatureHeader, secret) {
  const expected = createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex')

  const received = signatureHeader.trim()
  if (expected.length !== received.length) return false

  return timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  )
}

// Express: use express.raw({ type: 'application/json' }) or req.rawBody
// Then:
// if (!verifyRibbonpayWebhook(rawBody, req.headers['x-ribbonpay-signature'], WEBHOOK_SECRET)) {
//   return res.status(401).send('Invalid signature')
// }

PHP example (Magento / WooCommerce-style backends)

<?php
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_RIBBONPAY_SIGNATURE'] ?? '';
$secret = getenv('RIBBONPAY_WEBHOOK_SECRET');

$expected = hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
$externalOrderId = $payload['external_order_id'];
$decision = $payload['decision']; // SHIP or CANCEL

Your webhook handler must

Retry behavior

8. Edge cases and status reference

Idempotency

external_order_id is unique per merchant. Submitting the same ID twice returns the original order and decision (200) — no duplicate row is created. Safe to retry on network failures.

Payment error (payment_error)

If payment_status is one of declined, failed, error, or refused (case-insensitive), the order is recorded with status payment_error and is not scored for fraud review. No fulfillment action is expected from ribbonPay.

Merchant cancelled (merchant_cancelled)

If payment_status or order_status is cancelled, refunded, or voided (case-insensitive), the order is recorded as merchant_cancelled — the shopper or merchant cancelled before ribbonPay could decide.

Rate limiting (429)

Default limit: 60 requests per minute per merchant (configurable). Response includes:

{ "error": "rate_limited", "retry_after_seconds": 12 }

Header: Retry-After (seconds). Back off and retry.

Validation errors (400)

{
  "error": "invalid_request",
  "details": [ /* Zod issue objects */ ]
}

Common causes: missing required field, invalid email, country not 2 letters, card_bin not 6 digits, device_lat without device_lng, empty PATCH body, unknown JSON keys.

Error summary

9. Testing checklist

Use Postman, curl, or your HTTP client against your ribbonPay environment. Confirm each scenario and verify the order appears in the ribbonPay ops console.

Prerequisites

• Merchant account provisioned with API key and webhook signing secret
• webhook_url pointed at a test receiver (webhook.site, RequestBin, or local tunnel)
• Ops console access to resolve PENDING orders (for webhook end-to-end test)

POST /api/v1/orders

PATCH /api/v1/orders/{external_order_id}

Webhook receiver

End-to-end flow

9. Device collection (browser collector)

ribbonPay ships a hosted browser collector for Direct/API merchants and the WooCommerce plugin. It follows a Kount DDC-style pattern: the shopper's browser posts device signals keyed by a per-checkout session_id; your order POST/PATCH carries the same value as device_session_id; ribbonPay joins them server-side and derives a stable device_id fingerprint.

Shopify checkout uses a separate no-code Custom Pixel that feeds the same ingest endpoint — see shopify-device-collection-setup.md (ops-installed; not something the merchant integrates via this guide).

Site key

Ops provisions a publishable site key (rp_site_ + random suffix). This is not your secret rp_live_… API key. Never embed the live API key in storefront HTML.

Checkout embed

Generate a fresh session_id per checkout (UUID recommended). Set it in a first-party cookie if useful for your plugin, and pass the same value as device_session_id on POST /api/v1/orders.

<script
  src="https://YOUR_RIBBONPAY_HOST/device/v1/collector.js"
  data-rp-site-key="rp_site_xxxxxxxxxxxxxxxxxxxxxxxx"
  data-rp-session="YOUR_CHECKOUT_SESSION_ID"
  data-rp-ingest="https://YOUR_RIBBONPAY_HOST/api/device/v1/collect"
  async
></script>

Alternative config object (if you load the script programmatically):

window.ribbonpayDevice = {
  siteKey: 'rp_site_…',
  sessionId: 'YOUR_CHECKOUT_SESSION_ID',
  ingestUrl: 'https://YOUR_RIBBONPAY_HOST/api/device/v1/collect',
}

Ingest contract

Collection may arrive before or after the order POST; both orderings are supported. If signals arrive late, ribbonPay backfills device enrichment on pending review orders.

Order field

{
  "external_order_id": "ORD-10042",
  "device_session_id": "YOUR_CHECKOUT_SESSION_ID",
  "...": "..."
}

ribbonPay derives device_id from collected signals. Merchants may still send their own device_id; merchant-supplied values take precedence.

10. Known limitations

Quick reference

Auth: Authorization: Bearer rp_live_…

Decision webhook headers: X-Ribbonpay-Signature, optional X-Ribbonpay-Signature-Previous (rotation grace), X-Ribbonpay-Event: order.decision, optional X-Ribbonpay-Delivery-Id

Support: Include X-Request-Id from any API response when contacting ribbonPay.