Create a payment

curl --request POST \
  --url https://api.beta.suby.fi/v3/payments \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123",
  "amount": 2,
  "currency": "<string>",
  "displayName": "<string>",
  "displayDescription": "<string>",
  "displayImageUrl": "<string>",
  "customerId": "cus_abc123",
  "billingAddress": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "businessData": {
    "purchaseAsBusiness": true,
    "businessName": "<string>",
    "taxId": "<string>"
  },
  "customerPaymentMethodId": "pi_abc123",
  "card": {
    "tokenizedInstrument": "<string>",
    "paymentInstrumentId": "<string>",
    "providerCustomerId": "<string>",
    "threedsSessionId": "<string>"
  },
  "crypto": {
    "chainId": 2,
    "assetId": 2,
    "tokenAmount": "<string>",
    "payerAddress": "<string>"
  },
  "captureMethod": "automatic",
  "offSession": false,
  "savePaymentMethod": false,
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "externalRef": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.beta.suby.fi/v3/payments"

payload = {
    "productId": "pro_abc123",
    "amount": 2,
    "currency": "<string>",
    "displayName": "<string>",
    "displayDescription": "<string>",
    "displayImageUrl": "<string>",
    "customerId": "cus_abc123",
    "billingAddress": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "businessData": {
        "purchaseAsBusiness": True,
        "businessName": "<string>",
        "taxId": "<string>"
    },
    "customerPaymentMethodId": "pi_abc123",
    "card": {
        "tokenizedInstrument": "<string>",
        "paymentInstrumentId": "<string>",
        "providerCustomerId": "<string>",
        "threedsSessionId": "<string>"
    },
    "crypto": {
        "chainId": 2,
        "assetId": 2,
        "tokenAmount": "<string>",
        "payerAddress": "<string>"
    },
    "captureMethod": "automatic",
    "offSession": False,
    "savePaymentMethod": False,
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "externalRef": "<string>",
    "metadata": {}
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_abc123',
    amount: 2,
    currency: '<string>',
    displayName: '<string>',
    displayDescription: '<string>',
    displayImageUrl: '<string>',
    customerId: 'cus_abc123',
    billingAddress: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    businessData: {purchaseAsBusiness: true, businessName: '<string>', taxId: '<string>'},
    customerPaymentMethodId: 'pi_abc123',
    card: {
      tokenizedInstrument: '<string>',
      paymentInstrumentId: '<string>',
      providerCustomerId: '<string>',
      threedsSessionId: '<string>'
    },
    crypto: {chainId: 2, assetId: 2, tokenAmount: '<string>', payerAddress: '<string>'},
    captureMethod: 'automatic',
    offSession: false,
    savePaymentMethod: false,
    successUrl: '<string>',
    cancelUrl: '<string>',
    externalRef: '<string>',
    metadata: {}
  })
};

fetch('https://api.beta.suby.fi/v3/payments', 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.beta.suby.fi/v3/payments",
  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([
    'productId' => 'pro_abc123',
    'amount' => 2,
    'currency' => '<string>',
    'displayName' => '<string>',
    'displayDescription' => '<string>',
    'displayImageUrl' => '<string>',
    'customerId' => 'cus_abc123',
    'billingAddress' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postalCode' => '<string>',
        'country' => '<string>'
    ],
    'businessData' => [
        'purchaseAsBusiness' => true,
        'businessName' => '<string>',
        'taxId' => '<string>'
    ],
    'customerPaymentMethodId' => 'pi_abc123',
    'card' => [
        'tokenizedInstrument' => '<string>',
        'paymentInstrumentId' => '<string>',
        'providerCustomerId' => '<string>',
        'threedsSessionId' => '<string>'
    ],
    'crypto' => [
        'chainId' => 2,
        'assetId' => 2,
        'tokenAmount' => '<string>',
        'payerAddress' => '<string>'
    ],
    'captureMethod' => 'automatic',
    'offSession' => false,
    'savePaymentMethod' => false,
    'successUrl' => '<string>',
    'cancelUrl' => '<string>',
    'externalRef' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-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.beta.suby.fi/v3/payments"

	payload := strings.NewReader("{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	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.beta.suby.fi/v3/payments")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/payments")

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

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "success": true,
  "data": {
    "payment": {
      "id": "pay_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "subscriptionId": "<string>",
      "declineCode": "<string>",
      "displayName": "<string>",
      "displayDescription": "<string>",
      "displayImageUrl": "<string>",
      "priceCents": "<string>",
      "currency": "<string>",
      "tokenAmount": "<string>",
      "tokenFeeAmount": "<string>",
      "quoteFiatAmountCents": 123,
      "quoteFiatCurrency": "<string>",
      "grossAmountCents": 123,
      "platformFeeCents": 123,
      "merchantNetCents": 123,
      "vatAmountCents": 123,
      "vatRateBps": 123,
      "taxInclusive": true,
      "refundedAmountCents": 123,
      "refundedAt": "2023-11-07T05:31:56Z",
      "cryptoSettlementMode": "<string>",
      "settlementChainId": 123,
      "settlementAsset": "<string>",
      "settlementRecipient": "<string>",
      "depositAddress": "<string>",
      "settlementTxHash": "<string>",
      "successUrl": "<string>",
      "cancelUrl": "<string>",
      "externalRef": "<string>",
      "paymentReceivedAt": "2023-11-07T05:31:56Z",
      "paymentSettledAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "statusTimeline": [
        {
          "at": "2023-11-07T05:31:56Z"
        }
      ],
      "asset": {
        "chainId": 123,
        "symbol": "<string>",
        "decimals": 123,
        "address": "<string>"
      },
      "deposit": {
        "expected": "<string>",
        "received": "<string>",
        "remaining": "<string>",
        "confirmations": {
          "observed": 123,
          "required": 123,
          "detectedAt": "2023-11-07T05:31:56Z"
        },
        "warnings": [
          {
            "message": "<string>",
            "data": {}
          }
        ]
      }
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "redirectUrl": "<string>",
      "threeDsChallengeUrl": "<string>",
      "clientSecret": "<string>"
    },
    "instruction": {
      "kind": "qr_deposit",
      "chainId": 123,
      "depositAddress": "<string>",
      "expectedAmount": "<string>",
      "decimals": 123,
      "symbol": "<string>",
      "address": "<string>",
      "bip21Uri": "<string>",
      "surchargeNote": "<string>"
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": {
    "fieldErrors": [
      {
        "field": "method",
        "message": "method is a required field"
      }
    ]
  }
}

{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Too many requests"
}

Payments

Create a payment

Create a payment and dispatch it to the merchant’s configured provider. Provide either a productId or an amount + currency, and exactly one of customerId / customerData. Method-specific options are grouped: card/APM details go under card, crypto routing under crypto. For crypto, method=CRYPTO requires crypto.mode, crypto.chainId, and crypto.assetId.

Card flows return a checkout handle (redirect / 3DS / client secret); crypto flows return an instruction (QR deposit or wallet-connect calldata).

POST

payments

Create a payment

curl --request POST \
  --url https://api.beta.suby.fi/v3/payments \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_abc123",
  "amount": 2,
  "currency": "<string>",
  "displayName": "<string>",
  "displayDescription": "<string>",
  "displayImageUrl": "<string>",
  "customerId": "cus_abc123",
  "billingAddress": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postalCode": "<string>",
    "country": "<string>"
  },
  "businessData": {
    "purchaseAsBusiness": true,
    "businessName": "<string>",
    "taxId": "<string>"
  },
  "customerPaymentMethodId": "pi_abc123",
  "card": {
    "tokenizedInstrument": "<string>",
    "paymentInstrumentId": "<string>",
    "providerCustomerId": "<string>",
    "threedsSessionId": "<string>"
  },
  "crypto": {
    "chainId": 2,
    "assetId": 2,
    "tokenAmount": "<string>",
    "payerAddress": "<string>"
  },
  "captureMethod": "automatic",
  "offSession": false,
  "savePaymentMethod": false,
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "externalRef": "<string>",
  "metadata": {}
}
'

import requests

url = "https://api.beta.suby.fi/v3/payments"

payload = {
    "productId": "pro_abc123",
    "amount": 2,
    "currency": "<string>",
    "displayName": "<string>",
    "displayDescription": "<string>",
    "displayImageUrl": "<string>",
    "customerId": "cus_abc123",
    "billingAddress": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postalCode": "<string>",
        "country": "<string>"
    },
    "businessData": {
        "purchaseAsBusiness": True,
        "businessName": "<string>",
        "taxId": "<string>"
    },
    "customerPaymentMethodId": "pi_abc123",
    "card": {
        "tokenizedInstrument": "<string>",
        "paymentInstrumentId": "<string>",
        "providerCustomerId": "<string>",
        "threedsSessionId": "<string>"
    },
    "crypto": {
        "chainId": 2,
        "assetId": 2,
        "tokenAmount": "<string>",
        "payerAddress": "<string>"
    },
    "captureMethod": "automatic",
    "offSession": False,
    "savePaymentMethod": False,
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "externalRef": "<string>",
    "metadata": {}
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_abc123',
    amount: 2,
    currency: '<string>',
    displayName: '<string>',
    displayDescription: '<string>',
    displayImageUrl: '<string>',
    customerId: 'cus_abc123',
    billingAddress: {
      line1: '<string>',
      line2: '<string>',
      city: '<string>',
      state: '<string>',
      postalCode: '<string>',
      country: '<string>'
    },
    businessData: {purchaseAsBusiness: true, businessName: '<string>', taxId: '<string>'},
    customerPaymentMethodId: 'pi_abc123',
    card: {
      tokenizedInstrument: '<string>',
      paymentInstrumentId: '<string>',
      providerCustomerId: '<string>',
      threedsSessionId: '<string>'
    },
    crypto: {chainId: 2, assetId: 2, tokenAmount: '<string>', payerAddress: '<string>'},
    captureMethod: 'automatic',
    offSession: false,
    savePaymentMethod: false,
    successUrl: '<string>',
    cancelUrl: '<string>',
    externalRef: '<string>',
    metadata: {}
  })
};

fetch('https://api.beta.suby.fi/v3/payments', 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.beta.suby.fi/v3/payments",
  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([
    'productId' => 'pro_abc123',
    'amount' => 2,
    'currency' => '<string>',
    'displayName' => '<string>',
    'displayDescription' => '<string>',
    'displayImageUrl' => '<string>',
    'customerId' => 'cus_abc123',
    'billingAddress' => [
        'line1' => '<string>',
        'line2' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'postalCode' => '<string>',
        'country' => '<string>'
    ],
    'businessData' => [
        'purchaseAsBusiness' => true,
        'businessName' => '<string>',
        'taxId' => '<string>'
    ],
    'customerPaymentMethodId' => 'pi_abc123',
    'card' => [
        'tokenizedInstrument' => '<string>',
        'paymentInstrumentId' => '<string>',
        'providerCustomerId' => '<string>',
        'threedsSessionId' => '<string>'
    ],
    'crypto' => [
        'chainId' => 2,
        'assetId' => 2,
        'tokenAmount' => '<string>',
        'payerAddress' => '<string>'
    ],
    'captureMethod' => 'automatic',
    'offSession' => false,
    'savePaymentMethod' => false,
    'successUrl' => '<string>',
    'cancelUrl' => '<string>',
    'externalRef' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-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.beta.suby.fi/v3/payments"

	payload := strings.NewReader("{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	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.beta.suby.fi/v3/payments")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/payments")

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

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_abc123\",\n  \"amount\": 2,\n  \"currency\": \"<string>\",\n  \"displayName\": \"<string>\",\n  \"displayDescription\": \"<string>\",\n  \"displayImageUrl\": \"<string>\",\n  \"customerId\": \"cus_abc123\",\n  \"billingAddress\": {\n    \"line1\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"businessData\": {\n    \"purchaseAsBusiness\": true,\n    \"businessName\": \"<string>\",\n    \"taxId\": \"<string>\"\n  },\n  \"customerPaymentMethodId\": \"pi_abc123\",\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\",\n    \"paymentInstrumentId\": \"<string>\",\n    \"providerCustomerId\": \"<string>\",\n    \"threedsSessionId\": \"<string>\"\n  },\n  \"crypto\": {\n    \"chainId\": 2,\n    \"assetId\": 2,\n    \"tokenAmount\": \"<string>\",\n    \"payerAddress\": \"<string>\"\n  },\n  \"captureMethod\": \"automatic\",\n  \"offSession\": false,\n  \"savePaymentMethod\": false,\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\",\n  \"externalRef\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "success": true,
  "data": {
    "payment": {
      "id": "pay_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "subscriptionId": "<string>",
      "declineCode": "<string>",
      "displayName": "<string>",
      "displayDescription": "<string>",
      "displayImageUrl": "<string>",
      "priceCents": "<string>",
      "currency": "<string>",
      "tokenAmount": "<string>",
      "tokenFeeAmount": "<string>",
      "quoteFiatAmountCents": 123,
      "quoteFiatCurrency": "<string>",
      "grossAmountCents": 123,
      "platformFeeCents": 123,
      "merchantNetCents": 123,
      "vatAmountCents": 123,
      "vatRateBps": 123,
      "taxInclusive": true,
      "refundedAmountCents": 123,
      "refundedAt": "2023-11-07T05:31:56Z",
      "cryptoSettlementMode": "<string>",
      "settlementChainId": 123,
      "settlementAsset": "<string>",
      "settlementRecipient": "<string>",
      "depositAddress": "<string>",
      "settlementTxHash": "<string>",
      "successUrl": "<string>",
      "cancelUrl": "<string>",
      "externalRef": "<string>",
      "paymentReceivedAt": "2023-11-07T05:31:56Z",
      "paymentSettledAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "statusTimeline": [
        {
          "at": "2023-11-07T05:31:56Z"
        }
      ],
      "asset": {
        "chainId": 123,
        "symbol": "<string>",
        "decimals": 123,
        "address": "<string>"
      },
      "deposit": {
        "expected": "<string>",
        "received": "<string>",
        "remaining": "<string>",
        "confirmations": {
          "observed": 123,
          "required": 123,
          "detectedAt": "2023-11-07T05:31:56Z"
        },
        "warnings": [
          {
            "message": "<string>",
            "data": {}
          }
        ]
      }
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "redirectUrl": "<string>",
      "threeDsChallengeUrl": "<string>",
      "clientSecret": "<string>"
    },
    "instruction": {
      "kind": "qr_deposit",
      "chainId": 123,
      "depositAddress": "<string>",
      "expectedAmount": "<string>",
      "decimals": 123,
      "symbol": "<string>",
      "address": "<string>",
      "bip21Uri": "<string>",
      "surchargeNote": "<string>"
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found"
}

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Validation failed",
  "data": {
    "fieldErrors": [
      {
        "field": "method",
        "message": "method is a required field"
      }
    ]
  }
}

{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Too many requests"
}

Authorizations

X-Suby-Api-Key

string

header

required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key

string

Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first is still in flight → 409. See the Idempotency guide.

Maximum string length: 255

Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Body

application/json

Pricing: provide productId (uses the product's price snapshot) OR amount + currency (ad-hoc) — one is required. Customer: exactly one of customerId (existing) / customerData (created on the fly) is required — no anonymous charges. Method options are grouped: card for the card/APM family, crypto for method=CRYPTO; the block not matching method is ignored.

method

enum<string>

required

Available options:

CARD,

APPLE_PAY,

GOOGLE_PAY,

KLARNA,

IDEAL,

BANCONTACT,

TWINT,

BLIK,

AFFIRM,

MULTIBANCO,

PAYPAL,

SEPA_DIRECT_DEBIT,

ACH_DIRECT_DEBIT,

CRYPTO

productId

string

Charge this product (its priceCents/currency/display are snapshotted). Alternative to amount+currency.

Example:

"pro_abc123"

amount

integer

Ad-hoc amount in cents. Requires currency. Alternative to productId.

Required range: x >= 1

currency

string

ISO 4217. Required with amount.

Pattern: ^[A-Z]{3}$

displayName

string

Label snapshotted on the Payment (ad-hoc charges). Product-backed charges fall back to the product name.

Maximum string length: 200

displayDescription

string | null

Maximum string length: 500

displayImageUrl

string<uri> | null

taxBehavior

enum<string>

MoR VAT: exclusive (default) adds VAT on top of the price (buyer charged price + VAT); inclusive treats the price as VAT-inclusive (buyer charged the listed price, VAT extracted). Ignored when no VAT applies (non-MoR).

Available options:

inclusive,

exclusive

customerId

string

Existing customer. Mutually exclusive with customerData; one is required.

Example:

"cus_abc123"

customerData

object

Inline customer for create-on-the-fly. Mutually exclusive with customerId.

Show child attributes

billingAddress

object

Required by the PSP for card/APM when the stored customer has none (Adyen rejects an empty country). Ignored for crypto.

Show child attributes

businessData

object

B2B purchase details. Accepted on ALL accounts — businessName / taxId are always stored on the customer, and businessName doubles as the card holder name. The VAT reverse-charge it triggers (0% VAT except France) only takes effect on Merchant-of-Record accounts; on non-MoR accounts no VAT applies at all, so it has no tax effect.

Show child attributes

customerPaymentMethodId

string

Charge a saved instrument (pi_…). Required when offSession=true.

Example:

"pi_abc123"

card

object

Card / APM instrument options. Ignored on crypto rails. Identify what to charge either with a fresh tokenizedInstrument, or — for proactive 3DS — with the paymentInstrumentId + providerCustomerId + threedsSessionId trio returned by the 3DS session.

Show child attributes

crypto

object

Crypto routing options. Required when method=CRYPTO (mode, chainId and assetId are all mandatory then); ignored otherwise.

Show child attributes

captureMethod

enum<string>

default:automatic

automatic = auth+capture now (purchase). manual = authorize only → AUTHORIZED; settle later via /capture or release via /void. Card/APM only.

Available options:

automatic,

manual

offSession

boolean

default:false

Merchant-initiated debit of a saved instrument (no customer present). Requires customerId + customerPaymentMethodId.

savePaymentMethod

boolean

default:false

Store the instrument for later off-session debits. Requires customerId or customerData.

successUrl

string<uri>

cancelUrl

string<uri>

externalRef

string

Your reference, stored on the Payment for reconciliation.

Maximum string length: 120

metadata

object

Key-value pairs. ≤50 keys, keys ≤40 chars, values are strings ≤500 chars (or null to clear). Nested structures must be JSON-stringified into a single string value.

Show child attributes

Response

Payment created

success

boolean

required

Example:

true

data

object

required

Endpoint-specific payload.

Show child attributes

message

string

List payments Capture an authorized payment

Overview

Endpoints

Create a payment

Authorizations

Headers

Body

Response