Payment initiate

Start a one-time payment using your merchant app token. Amounts are major currency units (25 means USD 25, not 25 cents). These values are illustrative; use the first-payment guide for the runnable workflow.

POST https://api.tinkerpayments.com/v1/merchant/payment/initiate

Authorization: Bearer <app-token>
Content-Type: application/json
Idempotency-Key: <saved-unique-key>

{
  "amount": 25,
  "currency": "USD",
  "gateway": "stripe",
  "merchantReference": "ORDER-12345",
  "returnUrl": "https://your-app.example/payment/return",
  "customerEmail": "[email protected]"
}

Save the key and reuse the same payload after a timeout. HTTP 200 can replay saved initiation data; HTTP 202 means the same operation is executing or uncertain and must not be restarted with a new key. See the idempotency contract for retention, conflicts, and recovery boundaries.

HTTP 200: initiation accepted

{
  "success": true,
  "data": {
    "paymentReference": "cs_test_example",
    "status": "pending",
    "authorizationUrl": "https://checkout.stripe.com/..."
  }
}

Accepted initiation is pending collection. Complete a sandbox payment and signed callback.