Create Transaction

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_wallet": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
    "payer_email": "satoshi@starkfi.io",
    "chain_name": "arbitrum",
    "payer_token_symbol": "USDT",
    "transaction_type": "crypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_cpf": "12345678900",
    "payer_email": "satoshi@starkfi.io",
    "transaction_type": "pixcrypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "transaction_type": "cardcrypto",
    "payer_email": "john@example.com",
    "payer_name": "John Michael Smith",
    "payer_document": "123456789",
    "payer_document_type": "PASSPORT",
    "payer_ip": "200.100.50.25",
    "session_id": "optional-session-uuid",
    "payer_phone": {
      "country_code": "1",
      "area_code": "415",
      "number": "5550199"
    },
    "card_data": {
      "installments": 1,
      "statement_descriptor": "STARKNODE",
      "card_token": "token_wxDE5l3uGofL5KzR",
      "address": {
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "neighborhood": "SoMa",
        "street": "Market Street",
        "street_number": "101",
        "zipcode": "941071234",
        "complement": "Apt 4B"
      }
    }
  }'

const response = await fetch(
  "https://api.starkfi.io/payment/register/intents-create-transaction",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "<api_key>",
    },
    body: JSON.stringify({
      payment_id: "cmodpory6000001nyoe3d12m1",
      payer_wallet: "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
      payer_email: "satoshi@starkfi.io",
      chain_name: "arbitrum",
      payer_token_symbol: "USDT",
      transaction_type: "crypto",
    }),
  }
);

const data = await response.json();

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodi78b2000101pjezst1ics",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": {
      "schema_version": 1,
      "family": "evm",
      "chain_name": "arbitrum",
      "transactionRequest": {
        "from": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
        "to": "0x23183C87c9c6668edf5974893905AF475c3664c9",
        "data": "0x40180def...",
        "value": 0,
        "chainId": 42161,
        "gasLimit": "82499",
        "maxPriorityFeePerGas": "0",
        "maxFeePerGas": "52514800",
        "nonce": 36
      },
      "meta": {
        "source": "evm_split"
      }
    },
    "fiat_tx": {
      "message": "This details is available only for fiat payments"
    }
  }
}

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodhqf38000001pjju9kxlmb",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": "This details is available only for crypto payments",
    "fiat_tx": {
      "status": "ATIVA",
      "pix_key": "3254cbd2-75e5-4034-abdb-ba8eebcee742",
      "txid": "282910f46cb6420388c9887a",
      "pixCopiaECola": "00020101021226790014br.gov.bcb.p03***63047A85",
      "pix_qr_code_data_url": "data:image/png;base64,iVBORw0KGgo...",
      "calendar": {
        "criacao": "2026-04-24T19:37:30.608Z",
        "expiracao": 3600
      },
      "code": 201
    }
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "unauthorized",
  "message": "Invalid or missing API key."
}

{
  "statusCode": 400,
  "success": false,
  "status": "validation_error",
  "message": "Validation failed.",
  "errors": [
    {
      "field": "payment_id",
      "message": "payment_id is required."
    }
  ]
}

POST

payment

intents-create-transaction

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_wallet": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
    "payer_email": "satoshi@starkfi.io",
    "chain_name": "arbitrum",
    "payer_token_symbol": "USDT",
    "transaction_type": "crypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_cpf": "12345678900",
    "payer_email": "satoshi@starkfi.io",
    "transaction_type": "pixcrypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "transaction_type": "cardcrypto",
    "payer_email": "john@example.com",
    "payer_name": "John Michael Smith",
    "payer_document": "123456789",
    "payer_document_type": "PASSPORT",
    "payer_ip": "200.100.50.25",
    "session_id": "optional-session-uuid",
    "payer_phone": {
      "country_code": "1",
      "area_code": "415",
      "number": "5550199"
    },
    "card_data": {
      "installments": 1,
      "statement_descriptor": "STARKNODE",
      "card_token": "token_wxDE5l3uGofL5KzR",
      "address": {
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "neighborhood": "SoMa",
        "street": "Market Street",
        "street_number": "101",
        "zipcode": "941071234",
        "complement": "Apt 4B"
      }
    }
  }'

const response = await fetch(
  "https://api.starkfi.io/payment/register/intents-create-transaction",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "<api_key>",
    },
    body: JSON.stringify({
      payment_id: "cmodpory6000001nyoe3d12m1",
      payer_wallet: "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
      payer_email: "satoshi@starkfi.io",
      chain_name: "arbitrum",
      payer_token_symbol: "USDT",
      transaction_type: "crypto",
    }),
  }
);

const data = await response.json();

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodi78b2000101pjezst1ics",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": {
      "schema_version": 1,
      "family": "evm",
      "chain_name": "arbitrum",
      "transactionRequest": {
        "from": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
        "to": "0x23183C87c9c6668edf5974893905AF475c3664c9",
        "data": "0x40180def...",
        "value": 0,
        "chainId": 42161,
        "gasLimit": "82499",
        "maxPriorityFeePerGas": "0",
        "maxFeePerGas": "52514800",
        "nonce": 36
      },
      "meta": {
        "source": "evm_split"
      }
    },
    "fiat_tx": {
      "message": "This details is available only for fiat payments"
    }
  }
}

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodhqf38000001pjju9kxlmb",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": "This details is available only for crypto payments",
    "fiat_tx": {
      "status": "ATIVA",
      "pix_key": "3254cbd2-75e5-4034-abdb-ba8eebcee742",
      "txid": "282910f46cb6420388c9887a",
      "pixCopiaECola": "00020101021226790014br.gov.bcb.p03***63047A85",
      "pix_qr_code_data_url": "data:image/png;base64,iVBORw0KGgo...",
      "calendar": {
        "criacao": "2026-04-24T19:37:30.608Z",
        "expiracao": 3600
      },
      "code": 201
    }
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "unauthorized",
  "message": "Invalid or missing API key."
}

{
  "statusCode": 400,
  "success": false,
  "status": "validation_error",
  "message": "Validation failed.",
  "errors": [
    {
      "field": "payment_id",
      "message": "payment_id is required."
    }
  ]
}

string

required

Your StarkFi API key. You can find it in your dashboard.

The transaction type defines the required and optional request parameters. Always validate the specified type before building the request.

Checkout (order) flows do not require KYC/KYB — payments with order_code or executor_id: order_transaction skip verification.For financial transactions, fiat-related types require approved KYC/KYB when payer_email or payer_wallet is sent. Pure crypto never requires KYC/KYB. Errors: kyc_verification_required, kyc_not_approved. See StarkPay overview.

string

required

Payment ID returned by the Register Order Transaction endpoint.

enum<string>

required

Defines the payment method. Available options: crypto, pixcrypto, fiatcrypto, cardcrypto, cardfiat

string

required

Payer’s email address.

Crypto transaction fields

string

Payer’s public wallet address. Required for crypto transactions.

string

The chain the user will pay from (e.g. arbitrum, solana). Required for crypto transactions.

string

Token the user will pay with (e.g. USDC, SOL, ETH). Required for crypto transactions.

On-ramp (Pix / Fiat) transaction fields

string

Payer’s CPF or CNPJ. Required for pixcrypto and fiatcrypto transactions.

Credit card transaction fields

string

Payer’s full name. Required for cardcrypto and cardfiat transactions.

string

Payer’s document number. Required for card transactions.

enum<string>

Document type. Available options: PASSPORT, CPF, CNPJ. Required for card transactions.

string

Payer’s IP address. Required when using tokenized card.

string

Session identifier for fraud prevention. Required when using tokenized card.

object

Payer phone details. Required for card transactions.

Show payer_phone

string

required

Country code (e.g. 55 for Brazil, 1 for USA).

string

required

Area code / DDD (e.g. 11 for São Paulo).

string

required

Phone number.

object

Card payment configuration. Required for card transactions.

Show card_data

number

required

Number of installments. Only 1 (one-time payment) is currently supported.

string

required

Label that appears on the payer’s card statement (e.g. STARKNODE).

string

Tokenized card ID from the tokenization endpoint. Use this instead of raw card data.

object

Raw card details. Use only if not using card_token.

Show card

string

required

Card number (e.g. 4111111111111111).

string

required

Name printed on the card.

string

required

Card holder document number.

number

required

Expiration month (e.g. 12).

number

required

Expiration year (e.g. 2030).

string

required

Card security code.

string

required

Card brand (e.g. Visa, Mastercard).

object

required

Billing address for the card.

Show address

string

required

Country code (e.g. USA, BRA, BR).

string

required

State or province (e.g. CA, SP).

string

required

City name.

string

required

Neighborhood or district.

string

required

Street name.

string

required

Street number.

string

required

ZIP or postal code (numbers only).

string

Additional address info (e.g. Apt 4B). Optional.

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_wallet": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
    "payer_email": "satoshi@starkfi.io",
    "chain_name": "arbitrum",
    "payer_token_symbol": "USDT",
    "transaction_type": "crypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "payer_cpf": "12345678900",
    "payer_email": "satoshi@starkfi.io",
    "transaction_type": "pixcrypto"
  }'

curl --request POST \
  --url https://api.starkfi.io/payment/register/intents-create-transaction \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
    "payment_id": "cmodpory6000001nyoe3d12m1",
    "transaction_type": "cardcrypto",
    "payer_email": "john@example.com",
    "payer_name": "John Michael Smith",
    "payer_document": "123456789",
    "payer_document_type": "PASSPORT",
    "payer_ip": "200.100.50.25",
    "session_id": "optional-session-uuid",
    "payer_phone": {
      "country_code": "1",
      "area_code": "415",
      "number": "5550199"
    },
    "card_data": {
      "installments": 1,
      "statement_descriptor": "STARKNODE",
      "card_token": "token_wxDE5l3uGofL5KzR",
      "address": {
        "country": "US",
        "state": "CA",
        "city": "San Francisco",
        "neighborhood": "SoMa",
        "street": "Market Street",
        "street_number": "101",
        "zipcode": "941071234",
        "complement": "Apt 4B"
      }
    }
  }'

const response = await fetch(
  "https://api.starkfi.io/payment/register/intents-create-transaction",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "<api_key>",
    },
    body: JSON.stringify({
      payment_id: "cmodpory6000001nyoe3d12m1",
      payer_wallet: "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
      payer_email: "satoshi@starkfi.io",
      chain_name: "arbitrum",
      payer_token_symbol: "USDT",
      transaction_type: "crypto",
    }),
  }
);

const data = await response.json();

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodi78b2000101pjezst1ics",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": {
      "schema_version": 1,
      "family": "evm",
      "chain_name": "arbitrum",
      "transactionRequest": {
        "from": "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
        "to": "0x23183C87c9c6668edf5974893905AF475c3664c9",
        "data": "0x40180def...",
        "value": 0,
        "chainId": 42161,
        "gasLimit": "82499",
        "maxPriorityFeePerGas": "0",
        "maxFeePerGas": "52514800",
        "nonce": 36
      },
      "meta": {
        "source": "evm_split"
      }
    },
    "fiat_tx": {
      "message": "This details is available only for fiat payments"
    }
  }
}

{
  "statusCode": 201,
  "success": true,
  "status": "payment_registered",
  "message": "Payment has been registered",
  "data": {
    "payment_id": "cmodhqf38000001pjju9kxlmb",
    "session_payment": "https://app.starkfi.io/sessions/payment?token=<jwt>",
    "crypto_tx": "This details is available only for crypto payments",
    "fiat_tx": {
      "status": "ATIVA",
      "pix_key": "3254cbd2-75e5-4034-abdb-ba8eebcee742",
      "txid": "282910f46cb6420388c9887a",
      "pixCopiaECola": "00020101021226790014br.gov.bcb.p03***63047A85",
      "pix_qr_code_data_url": "data:image/png;base64,iVBORw0KGgo...",
      "calendar": {
        "criacao": "2026-04-24T19:37:30.608Z",
        "expiracao": 3600
      },
      "code": 201
    }
  }
}

{
  "statusCode": 401,
  "success": false,
  "status": "unauthorized",
  "message": "Invalid or missing API key."
}

{
  "statusCode": 400,
  "success": false,
  "status": "validation_error",
  "message": "Validation failed.",
  "errors": [
    {
      "field": "payment_id",
      "message": "payment_id is required."
    }
  ]
}

Response

number

required

HTTP status code. Returns 201 on success.

boolean

required

Whether the request succeeded.

string

required

Status label (e.g. payment_registered).

string

required

Human-readable response message.

object

required

Transaction data payload.

Show data

string

required

Unique identifier for this payment. Use it to check payment status or broadcast the transaction.

string

JWT-signed URL for the hosted payment session page.

object | string

Unsigned EVM or Solana transaction object ready for signing. Returns a message string for non-crypto payment types.

Show crypto_tx (EVM)

string

Transaction family (evm or solana).

string

Target chain (e.g. arbitrum).

number

Schema version.

object

Raw EVM transaction params: from, to, data, value, chainId, gasLimit, maxFeePerGas, maxPriorityFeePerGas, nonce.

object

Internal metadata (e.g. source: "evm_split").

object | string

Fiat payment data (Pix QR code, key, txid). Returns a message string for crypto-only transactions.

Show fiat_tx (Pix)

string

Pix charge status (e.g. ATIVA).

string

Pix key (chave) for this charge.

string

Pix transaction ID.

string

Pix copy-and-paste code.

string

Base64-encoded PNG QR code image ready to display.

object

Creation timestamp (criacao) and expiration in seconds (expiracao).

Signing a transaction

Direct on-chain submission is not allowed and may result in failure or rejection. All transactions must be signed locally and then submitted exclusively through the Broadcast endpoint.

After receiving crypto_tx, sign it with the user’s wallet before broadcasting.

EVM (ethers.js)
Solana (web3.js)

import { Wallet } from "ethers";

const privateKey = "YOUR_PRIVATE_KEY";
const wallet = new Wallet(privateKey);

const tx = {
  from:                 "0x9b57847b69D0354837F7b723133B9dBCbefb4F9F",
  to:                   "0x23183C87c9c6668edf5974893905AF475c3664c9",
  data:                 "0x40180def...",
  value:                0n,
  chainId:              42161,
  gasLimit:             82499n,
  maxPriorityFeePerGas: 0n,
  maxFeePerGas:         52514800n,
  nonce:                36,
  type:                 2,
};

const signedTx = await wallet.signTransaction(tx);
console.log("Signed transaction:", signedTx);

import { Connection, Transaction, Keypair } from "@solana/web3.js";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const keypair = Keypair.fromSecretKey(secretKey);

// Reconstruct transaction from crypto_tx data
const transaction = Transaction.from(Buffer.from(crypto_tx.serialized, "base64"));
transaction.sign(keypair);

const signedTx = transaction.serialize().toString("base64");
console.log("Signed transaction:", signedTx);

You can use an external wallet provider like Privy.io to sign transactions without exposing private keys. Never call sendTransaction directly — always go through the broadcast endpoint.

Card tokenization

Use tokenization to avoid handling raw card data. This improves security and helps ensure PCI compliance.

Endpoint: POST https://api.starkfi.io/payment/card/tokenize

string

required

Payment type. Use card.

object

required

Card details to tokenize.

Show card

string

required

Card number.

string

required

Name of the card holder.

string

required

Card holder document number (CPF).

number

required

Expiration month (1–12).

number

required

Expiration year (e.g. 30 for 2030).

string

required

Card security code.

Tokenization response:

{
  "id": "token_wxDE5l3uGofL5KzR",
  "type": "card",
  "created_at": "2026-04-25T17:32:22Z",
  "expires_at": "2026-04-25T17:33:22Z",
  "card": {
    "first_six_digits": "400000",
    "last_four_digits": "0010",
    "holder_name": "Tony Stark",
    "holder_document": "93095135270",
    "exp_month": 1,
    "exp_year": 30,
    "brand": "Visa"
  }
}

Pass the returned id as card_data.card_token in the create transaction request.

Card payment support is currently limited to CardCrypto. Only one-time transactions are supported. Enablement requires a minimum lead time of 7 days and must be aligned in advance with the sales team. To use any payment method involving the traditional financial system (PIX, fiat, card), complete KYC/KYB procedures with the account management team.

API documentation

StarkPay

Orders

Yield Aggregator

KYC

Quote

Crypto transaction fields

On-ramp (Pix / Fiat) transaction fields

Credit card transaction fields

Response

Signing a transaction

Card tokenization

​Crypto transaction fields

​On-ramp (Pix / Fiat) transaction fields

​Credit card transaction fields

​Response

​Signing a transaction

​Card tokenization

Crypto transaction fields

On-ramp (Pix / Fiat) transaction fields

Credit card transaction fields

Response

Signing a transaction

Card tokenization