v9

OpenAPI 3.1.02026-08-043703845.2 MB

Payments

Update payment return URL

Changes where the buyer lands after completing an off-site step, up until they return. Accepts either a secret key or the payment's own client_secret, so the surface that knows the final destination can set it.

patch/payments/{payment_id}/return_url

Path parameters

payment_idstring required

The unique identifier of the payment.

Request body

return_urlstring required

Where the buyer continues after completing an off-site step. Must be an absolute https URL without credentials, at most 2,048 characters.

Example request

{
  "return_url": "https://merchant.example/thanks"
}

Response

Return URL updated

idstring required

The payment this status describes, prefixed pay_.

objectstring required

Always payment_status.

return_urlstring nullable required

Where to send the buyer once the payment reaches a resting state, or null to leave them where they are. Editable until they return — see the return_url operation.

How far the payment has got. requires_confirmation — nothing attempted yet, or the last attempt failed and can be retried. requires_action — the buyer has a step outstanding; see next_action. confirming — the buyer has done their part and the processor is deciding. processing — the money is moving; see processing_details. succeeded — collected. canceled — voided or written off.

Example response

{
  "next_action": {
    "type": "redirect"
  },
  "status": "requires_confirmation"
}