Create a hosted payment page payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments/hpp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 2500,
  "currency": "EUR",
  "merchant_reference": 2345678901,
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "return_url": "https://shop.example.com/checkout/complete"
}
'

import requests

url = "https://api.flowlix.dev/v1/payments/hpp"

payload = {
    "amount": 2500,
    "currency": "EUR",
    "merchant_reference": 2345678901,
    "billing_details": {
        "email": "jenny@example.com",
        "first_name": "Jenny",
        "last_name": "Rosen",
        "phone": "+491701234567",
        "address": {
            "line1": "Kurfuerstendamm 21",
            "city": "Berlin",
            "postal_code": "10719",
            "country": "DE"
        }
    },
    "return_url": "https://shop.example.com/checkout/complete"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 2500,
    currency: 'EUR',
    merchant_reference: 2345678901,
    billing_details: {
      email: 'jenny@example.com',
      first_name: 'Jenny',
      last_name: 'Rosen',
      phone: '+491701234567',
      address: {
        line1: 'Kurfuerstendamm 21',
        city: 'Berlin',
        postal_code: '10719',
        country: 'DE'
      }
    },
    return_url: 'https://shop.example.com/checkout/complete'
  })
};

fetch('https://api.flowlix.dev/v1/payments/hpp', 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.flowlix.dev/v1/payments/hpp",
  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' => 2500,
    'currency' => 'EUR',
    'merchant_reference' => 2345678901,
    'billing_details' => [
        'email' => 'jenny@example.com',
        'first_name' => 'Jenny',
        'last_name' => 'Rosen',
        'phone' => '+491701234567',
        'address' => [
                'line1' => 'Kurfuerstendamm 21',
                'city' => 'Berlin',
                'postal_code' => '10719',
                'country' => 'DE'
        ]
    ],
    'return_url' => 'https://shop.example.com/checkout/complete'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.flowlix.dev/v1/payments/hpp"

	payload := strings.NewReader("{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.flowlix.dev/v1/payments/hpp")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.dev/v1/payments/hpp")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}"

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

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds.",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "expired_at": null
  },
  "next_action": {
    "type": "redirect",
    "reason": "three_d_secure",
    "redirect_url": "https://return.wlpg.io/fingerprint/abc"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

Payments

Create a hosted payment page payment

Creates a hosted payment page payment attempt. Redirect the customer to next_action.redirect_url to complete the next_action.reason customer action. The required-action URL is opaque and may later change from the hosted page to a 3D Secure browser action. Use the latest next_action.redirect_url from GET /v1/payments/{id}, and avoid redirect loops when the URL is unchanged.

billing_details is required for HPP and is used to prefill the hosted page. If the customer edits the billing details on the hosted page, the customer-entered values become authoritative for the payment.

return_url is the merchant URL where the customer is sent after completing or abandoning the hosted payment page. Return URL query parameters are UX hints only; merchants must use GET /v1/payments/{id} or webhooks as the source of truth.

Use the Idempotency-Key header to safely retry requests.

POST

payments

hpp

Create a hosted payment page payment

curl --request POST \
  --url https://api.flowlix.dev/v1/payments/hpp \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 2500,
  "currency": "EUR",
  "merchant_reference": 2345678901,
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "city": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "return_url": "https://shop.example.com/checkout/complete"
}
'

import requests

url = "https://api.flowlix.dev/v1/payments/hpp"

payload = {
    "amount": 2500,
    "currency": "EUR",
    "merchant_reference": 2345678901,
    "billing_details": {
        "email": "jenny@example.com",
        "first_name": "Jenny",
        "last_name": "Rosen",
        "phone": "+491701234567",
        "address": {
            "line1": "Kurfuerstendamm 21",
            "city": "Berlin",
            "postal_code": "10719",
            "country": "DE"
        }
    },
    "return_url": "https://shop.example.com/checkout/complete"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 2500,
    currency: 'EUR',
    merchant_reference: 2345678901,
    billing_details: {
      email: 'jenny@example.com',
      first_name: 'Jenny',
      last_name: 'Rosen',
      phone: '+491701234567',
      address: {
        line1: 'Kurfuerstendamm 21',
        city: 'Berlin',
        postal_code: '10719',
        country: 'DE'
      }
    },
    return_url: 'https://shop.example.com/checkout/complete'
  })
};

fetch('https://api.flowlix.dev/v1/payments/hpp', 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.flowlix.dev/v1/payments/hpp",
  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' => 2500,
    'currency' => 'EUR',
    'merchant_reference' => 2345678901,
    'billing_details' => [
        'email' => 'jenny@example.com',
        'first_name' => 'Jenny',
        'last_name' => 'Rosen',
        'phone' => '+491701234567',
        'address' => [
                'line1' => 'Kurfuerstendamm 21',
                'city' => 'Berlin',
                'postal_code' => '10719',
                'country' => 'DE'
        ]
    ],
    'return_url' => 'https://shop.example.com/checkout/complete'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.flowlix.dev/v1/payments/hpp"

	payload := strings.NewReader("{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.flowlix.dev/v1/payments/hpp")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.flowlix.dev/v1/payments/hpp")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 2500,\n  \"currency\": \"EUR\",\n  \"merchant_reference\": 2345678901,\n  \"billing_details\": {\n    \"email\": \"jenny@example.com\",\n    \"first_name\": \"Jenny\",\n    \"last_name\": \"Rosen\",\n    \"phone\": \"+491701234567\",\n    \"address\": {\n      \"line1\": \"Kurfuerstendamm 21\",\n      \"city\": \"Berlin\",\n      \"postal_code\": \"10719\",\n      \"country\": \"DE\"\n    }\n  },\n  \"return_url\": \"https://shop.example.com/checkout/complete\"\n}"

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

{
  "id": "pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E",
  "amount": 4999,
  "currency": "EUR",
  "status": "SUCCEEDED",
  "integration_type": "DIRECT",
  "amount_refunded": 0,
  "amount_refundable": 4999,
  "created_at": 1719792000,
  "livemode": false,
  "merchant_reference": 1234567890,
  "description": "Order #1234",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "DE"
  },
  "billing_details": {
    "email": "jenny@example.com",
    "first_name": "Jenny",
    "last_name": "Rosen",
    "phone": "+491701234567",
    "address": {
      "line1": "Kurfuerstendamm 21",
      "line2": "Apartment 4B",
      "city": "Berlin",
      "state": "Berlin",
      "postal_code": "10719",
      "country": "DE"
    }
  },
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds.",
  "refunds": [],
  "status_transitions": {
    "requires_action_at": null,
    "processing_at": 1719792002,
    "succeeded_at": 1719792042,
    "failed_at": null,
    "expired_at": null
  },
  "next_action": {
    "type": "redirect",
    "reason": "three_d_secure",
    "redirect_url": "https://return.wlpg.io/fingerprint/abc"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

{
  "error": {
    "message": "One or more request parameters failed validation.",
    "code": "parameter_invalid",
    "param": "payment_method_data[card][number]",
    "doc_url": "https://docs.flowlix.dev",
    "request_id": "req_abc123def456"
  }
}

Authorizations

Authorization

string

header

required

Use your secret API key as the Bearer token. Test mode keys start with api_test_sk_ and live mode keys start with api_live_sk_. Both modes use the same API host; the mode is determined by the key.

Authorization: Bearer api_test_sk_abc123def456

Headers

Idempotency-Key

string

required

A unique key to ensure the request is processed only once. If a request with the same idempotency key and the same body has already been processed successfully, the original response is returned. Non-2xx responses are not cached, so callers may retry after errors. Keys expire after 24 hours.

For one-shot requests, such as creating a payment from a checkout button, a random UUIDv4 is fine. For requests tied to a specific business operation, such as refunding an order, a deterministic key is preferred so retries collapse correctly across processes.

Maximum string length: 255

Body

application/json

amount

integer<int64>

required

Payment amount in minor units.

Required range: x >= 1

Example:

2500

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

billing_details

object

required

Show child attributes

return_url

string<uri>

required

Merchant URL where the customer returns after hosted payment completion or abandonment.

Example:

"https://shop.example.com/checkout/complete"

merchant_reference

integer<int64>

Optional merchant-side reconciliation reference. The value must contain exactly 10 decimal digits and does not provide idempotency by itself.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

description

string

Merchant-provided payment description.

Maximum string length: 500

Example:

"Order #5678"

Response

Hosted payment page payment accepted and a Payment object was created. When provider submission succeeds, the payment moves directly from PENDING to REQUIRES_ACTION with next_action.reason and next_action.redirect_url; it does not pass through PROCESSING before customer redirect. Use the Payment object's status from GET /v1/payments/{id} or webhooks as the source of truth for the final outcome.

A Payment represents one attempt to collect funds from the customer. Merchants can use merchant_reference to associate multiple payment attempts with the same order or checkout in their own systems.

string

required

Unique opaque identifier for a payment (pay_ prefix + random alphanumeric suffix).

Pattern: ^pay_[A-Za-z0-9]{24}$

Example:

"pay_q7Mk2Np8Vr4Xt6Yz9Ab3Cd5E"

amount

integer<int64>

required

Payment amount in minor units.

Required range: x >= 1

Example:

4999

currency

enum<string>

required

Three-letter ISO 4217 currency code. Currently supported for card acquiring: EUR.

Available options:

EUR

Example:

"EUR"

status

enum<string>

required

Current status of a payment attempt.

PENDING -- The payment was accepted by Flowlix and is awaiting provider submission or the next lifecycle decision.
REQUIRES_ACTION -- Customer action is required, such as completing 3D Secure authentication or a hosted payment page.
PROCESSING -- The payment is being processed by downstream payment systems.
SUCCEEDED -- The payment completed successfully.
FAILED -- The payment was declined or failed permanently.
CANCELED -- The payment was canceled before completion.
EXPIRED -- The customer did not complete a required action before its expiry time.

Available options:

PENDING,

REQUIRES_ACTION,

PROCESSING,

SUCCEEDED,

FAILED,

CANCELED,

EXPIRED

Example:

"SUCCEEDED"

integration_type

enum<string>

required

How the payment was collected. This is separate from the payment method instrument, such as card or a future wallet.

Available options:

DIRECT,

HOSTED_PAYMENT_PAGE

Example:

"DIRECT"

amount_refunded

integer<int64>

required

Total amount successfully refunded so far, in minor units.

Required range: x >= 0

Example:

0

amount_refundable

integer<int64>

required

Remaining amount that can be refunded, in minor units.

Required range: x >= 0

Example:

4999

created_at

integer<int64>

required

Unix timestamp when the payment was created.

Example:

1719792000

livemode

boolean

required

Whether this payment was created using a live API key.

Example:

false

merchant_reference

integer<int64> | null

Merchant-side reconciliation reference, if provided.

Required range: 1000000000 <= x <= 9999999999

Example:

1234567890

description

string | null

Merchant-provided payment description.

Example:

"Order #1234"

card

object | null

Masked card details, or null before card details are available.

Show child attributes

billing_details

object | null

Billing details captured for the payment, if available.

Show child attributes

failure_code

enum<string> | null

Machine-readable reason code when the payment reaches a terminal failed status.

Available options:

invalid_request,

not_found,

processor_error,

processor_unavailable,

generic_decline,

do_not_honor,

issuer_declined,

insufficient_funds,

invalid_number,

invalid_expiry,

expired_card,

invalid_amount,

invalid_currency,

not_permitted,

cardholder_limit,

card_velocity_exceeded,

lost_card,

stolen_card,

suspect_fraud,

fraud_filter,

payment_canceled,

three_d_secure_failed,

three_d_secure_timeout,

three_d_secure_not_supported,

three_d_secure_error

Example:

"insufficient_funds"

failure_message

string | null

Human-readable explanation when the payment reaches a terminal failed status.

Example:

"The card has insufficient funds."

refunds

object[]

Refunds created for this payment, oldest first.

Show child attributes

status_transitions

object

Timestamps for important payment status transitions.

Show child attributes

next_action

object | null

Customer action required to continue the payment.

Show child attributes

Create a Direct API payment

Retrieve a payment

⌘I

Get started

Guides

Error handling

Payments API

Create a hosted payment page payment

Authorizations

Headers

Body

Response