Create Transaction - StarkFi Documentation

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"
  }'

{
  "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"
    }
  }
}

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"
  }'

{
  "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"
    }
  }
}

x-api-key

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.

payment_id

string

required

Payment ID returned by the Register Order Transaction endpoint.

transaction_type

enum<string>

required

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

payer_email

string

required

Payer’s email address.

Crypto transaction fields

payer_wallet

string

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

chain_name

string

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

payer_token_symbol

string

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

On-ramp (Pix / Fiat) transaction fields

payer_cpf

string

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

Credit card transaction fields

payer_name

string

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

payer_document

string

Payer’s document number. Required for card transactions.

payer_document_type

enum<string>

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

payer_ip

string

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

session_id

string

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

payer_phone

object

Payer phone details. Required for card transactions.

Show payer_phone

country_code

string

required

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

area_code

string

required

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

number

string

required

Phone number.

card_data

object

Card payment configuration. Required for card transactions.

Show card_data

installments

number

required

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

statement_descriptor

string

required

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

card_token

string

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

card

object

Raw card details. Use only if not using card_token.

Show card

number

string

required

Card number (e.g. 4111111111111111).

holder_name

string

required

Name printed on the card.

holder_document

string

required

Card holder document number.

exp_month

number

required

Expiration month (e.g. 12).

exp_year

number

required

Expiration year (e.g. 2030).

cvv

string

required

Card security code.

brand

string

required

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

address

object

required

Billing address for the card.

Show address

country

string

required

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

state

string

required

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

city

string

required

City name.

neighborhood

string

required

Neighborhood or district.

street

string

required

Street name.

street_number

string

required

Street number.

zipcode

string

required

ZIP or postal code (numbers only).

complement

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"
  }'

{
  "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"
    }
  }
}

Response

statusCode

number

required

HTTP status code. Returns 201 on success.

success

boolean

required

Whether the request succeeded.

status

string

required

Status label (e.g. payment_registered).

message

string

required

Human-readable response message.

data

object

required

Transaction data payload.

Show data

payment_id

string

required

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

session_payment

string

JWT-signed URL for the hosted payment session page.

crypto_tx

object | string

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

Show crypto_tx (EVM)

family

string

Transaction family (evm or solana).

chain_name

string

Target chain (e.g. arbitrum).

schema_version

number

Schema version.

transactionRequest

object

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

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

type

string

required

Payment type. Use card.

card

object

required

Card details to tokenize.

Show card

number

string

required

Card number.

holder_name

string

required

Name of the card holder.

holder_document

string

required

Card holder document number (CPF).

exp_month

number

required

Expiration month (1–12).

exp_year

number

required

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

cvv

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.

​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