Create Payment Intent

curl --request POST \
  --url https://api.zopay.cash/connect/v1/payment-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1,
  "currencies": [
    "<string>"
  ],
  "external_ref": "<string>",
  "description": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.zopay.cash/connect/v1/payment-intents"

payload = {
    "amount": 1,
    "currencies": ["<string>"],
    "external_ref": "<string>",
    "description": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 1,
    currencies: ['<string>'],
    external_ref: '<string>',
    description: '<string>',
    metadata: {}
  })
};

fetch('https://api.zopay.cash/connect/v1/payment-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zopay.cash/connect/v1/payment-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 1,
    'currencies' => [
        '<string>'
    ],
    'external_ref' => '<string>',
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zopay.cash/connect/v1/payment-intents"

	payload := strings.NewReader("{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zopay.cash/connect/v1/payment-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zopay.cash/connect/v1/payment-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "currency": "<string>",
  "object": "payment_intent",
  "amount": 123,
  "status": "<string>",
  "ref_code": "<string>",
  "external_ref": "<string>",
  "description": "<string>",
  "metadata": {},
  "addresses": [
    {
      "asset": "<string>",
      "address": "<string>",
      "network": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deposit": {
    "amount_received": 123,
    "currency": "<string>",
    "network": "<string>",
    "address_receiver": "<string>",
    "address_sender": "<string>",
    "tx_hash": "<string>"
  },
  "amount_received": 0,
  "amount_remaining": 0,
  "partial_payment": false
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

POST

payment-intents

Create Payment Intent

curl --request POST \
  --url https://api.zopay.cash/connect/v1/payment-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 1,
  "currencies": [
    "<string>"
  ],
  "external_ref": "<string>",
  "description": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.zopay.cash/connect/v1/payment-intents"

payload = {
    "amount": 1,
    "currencies": ["<string>"],
    "external_ref": "<string>",
    "description": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 1,
    currencies: ['<string>'],
    external_ref: '<string>',
    description: '<string>',
    metadata: {}
  })
};

fetch('https://api.zopay.cash/connect/v1/payment-intents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zopay.cash/connect/v1/payment-intents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 1,
    'currencies' => [
        '<string>'
    ],
    'external_ref' => '<string>',
    'description' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zopay.cash/connect/v1/payment-intents"

	payload := strings.NewReader("{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zopay.cash/connect/v1/payment-intents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zopay.cash/connect/v1/payment-intents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 1,\n  \"currencies\": [\n    \"<string>\"\n  ],\n  \"external_ref\": \"<string>\",\n  \"description\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "currency": "<string>",
  "object": "payment_intent",
  "amount": 123,
  "status": "<string>",
  "ref_code": "<string>",
  "external_ref": "<string>",
  "description": "<string>",
  "metadata": {},
  "addresses": [
    {
      "asset": "<string>",
      "address": "<string>",
      "network": "<string>"
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "deposit": {
    "amount_received": 123,
    "currency": "<string>",
    "network": "<string>",
    "address_receiver": "<string>",
    "address_sender": "<string>",
    "tx_hash": "<string>"
  },
  "amount_received": 0,
  "amount_remaining": 0,
  "partial_payment": false
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Missing or malformed Authorization header. Send: Authorization: Bearer sk_live_... or sk_test_...",
    "doc_url": "https://docs.zopay.cash/errors/authentication_required",
    "param": "currencies"
  }
}

Mint a payment intent for the partner org. Idempotency: the Idempotency-Key header is required for this endpoint (enforced by idempotency_required). Same key + same body within 24h replays the original response verbatim. Same key + different body returns 409 idempotency_conflict. Unlike the address-creation flow, the underlying intent create is NOT idempotent on its own (it mints a fresh ref_code per call, so a naive retry would create two intents). The Idempotency-Key store is the only safety net here — without the header a retry mints a second intent. Partners SHOULD send the header on every POST. Dependency order: idem is taken before auth so the Idempotency-Key header is parsed (which can 400 on its own) before the DB hit for the scope check. Sandbox routing: sk_test_… keys (auth.mode == "sandbox") are routed to ConnectPaymentIntentsSandboxService, which makes no payment-server / BitGo / Rhino calls and persists the intent with deterministic fake addresses. sk_live_… keys continue to hit the real path through PaymentIntentService.create_payment_link.

Authorizations

Authorization

string

header

required

Paste your Connect API key (sk_live_… for production, sk_test_… for sandbox) without the Bearer prefix. Mint and rotate keys from the admin panel.

Headers

Idempotency-Key

string | null

Body

application/json

Request body for POST /connect/v1/payment-intents.

Forbidden extras: typo'd field names surface as a 422 rather than being silently ignored. Partners can recover by checking their request body shape against the docs.

All amount handling is in the intent's primary currency (currencies[0]). Multi-currency intents accept the same nominal amount across every currency -- there is no per-currency pricing slot here. If a partner needs per-currency pricing they can either mint one intent per currency or call a future quote API.

amount

required

Requested amount in the primary currency. Decimal string preferred to avoid float-precision loss.

Required range: x > 0

currencies

string[]

required

Asset codes the intent will accept, in priority order. First entry is the primary currency (drives the merchant-facing amount column). Each currency expands to all active networks server-side.

Required array length: 1 - 10 elements

external_ref

string | null

Partner-supplied attribution key. Stamped on the intent so webhooks and list filters can correlate back to your internal user. Omit if no per-user attribution applies (e.g. tenant-treasury collection page).

Maximum string length: 255

description

string | null

Free-form description, echoed back to the partner.

Maximum string length: 500

metadata

Metadata · object | null

Free-form JSON object for partner-side bookkeeping. Capped at 50 keys / 500-char values per key.

Response

Successful Response

Stripe-shaped payment intent envelope.

string

required

Payment intent UUID. Pass to GET /payment-intents/:id.

currency

string

required

Primary asset code, uppercase (e.g. USDT).

object

string

default:payment_intent

Always payment_intent. Stripe convention.

amount

number | null

Requested amount in the intent's primary asset.

status

string | null

Intent status. One of: pending, partial, completed, expired (snake_case, Stripe-compatible).

ref_code

string | null

5-character public-page identifier. Embedded in hosted checkout URLs (zopay.cash/pay/<ref_code>).

external_ref

string | null

Partner-supplied attribution key as passed to POST /payment-intents. Echoed verbatim. Use for your own per-user reconciliation.

description

string | null

Partner-supplied description, echoed verbatim.

metadata

Metadata · object | null

Partner-supplied metadata, echoed verbatim. NULL when no metadata was sent at creation.

addresses

ConnectPaymentIntentAddress · object[]

Per (asset, network) deposit destinations. One row per currency / network pair available on this intent.

Show child attributes

created_at

string<date-time> | null

When the intent was minted.

expires_at

string<date-time> | null

When the intent stops accepting deposits.

completed_at

string<date-time> | null

When the intent transitioned to status='completed'. NULL while pending. Idempotency anchor for the completion transition -- a retried call sees the same value, never a fresh one.

deposit

ConnectPaymentIntentDeposit · object | null

Chain-side details of the deposit that fulfilled this intent. NULL while pending; populated on completion. Field-for-field parity with the payment_intent.completed webhook event payload so pull and push reconciliation see one shape. On a partial-then-complete intent this object reflects the LATEST deposit, not the cumulative total; use amount_received for the cumulative figure.

Show child attributes

amount_received

number

default:0

Cumulative amount credited against this intent across all completed deposits. Always present; defaults to 0.0 when nothing has landed yet. On a partial payment this is the partial total; once the intent transitions to completed it equals (or slightly exceeds, by up to the 0.01 tolerance) amount.

amount_remaining

number

default:0

Raw remaining amount: max(0, amount - amount_received). No tolerance applied -- partners that want to render a 'pay X more' UI should check partial_payment first and read this value as the literal shortfall. A near-complete intent within the 0.01 tolerance shows a small positive value here but partial_payment=false.

partial_payment

boolean

default:false

True iff the intent has received at least one deposit but is not yet completed: amount_received > 0 AND status == 'pending'. Use this as the canonical 'is incomplete' boolean for partial-payment UI. Tolerance is handled transitively through status: the credit flow only leaves the intent in pending when the cumulative received amount is below the (amount - 0.01) threshold, so a near-complete intent within tolerance has already transitioned to completed and surfaces as partial_payment=false here.

Comenzando

Payment Intents

Addresses

Balances

Transactions

Payouts

Capabilities

Health

Events

Sandbox (test helpers)

Conversions (coming soon)

Ramps (coming soon)

Webhooks (coming soon)

Create Payment Intent

Authorizations

Headers

Body

Response