Skip to Content
DocsFor DevelopersAPIInvoice and Payout APIs

Invoice and Payout APIs

Use the Invoice and Payout APIs when your backend needs to create finance-team workflows in KryptoGO Studio with a Studio API key.

Call these APIs only from your server. Never expose a Studio API key in browser, mobile app, or other client-side code.

Authentication

Every request uses your Studio API key:

X-STUDIO-API-KEY: YOUR_API_KEY

Create endpoints also require your Studio OAuth client id:

X-Client-ID: YOUR_CLIENT_ID

If you include client_id in the JSON body for compatibility with Studio dashboard requests, it must match X-Client-ID.

Permissions

The API key acts as the Studio user that created it. That user must have the matching Transfer role:

Endpoint groupRequired permission
Create or update invoice intentstransfer:create
Cancel invoice intentstransfer:create
Approve or reject invoice intentstransfer:approve
Sign or refund invoice intentstransfer:sign
Create or update payout intentstransfer:create
Approve or reject payout intentstransfer:approve
Refund payout intentstransfer:sign
Get/list invoice or payout records and invoice logstransfer:read

Invoice endpoints

MethodEndpointRequestSuccess response
POST/v1/studio/api/invoice/intentInvoiceCreateRequestEnvelope<InvoiceIntent>
GET/v1/studio/api/invoice/intent/{id}Path idEnvelope<InvoiceIntent>
PUT/v1/studio/api/invoice/intent/{id}Path id + InvoiceUpdateRequestEnvelope<InvoiceIntent>
POST/v1/studio/api/invoice/intent/{id}/cancelPath id + optional CancelRequestEnvelope<InvoiceIntent>
POST/v1/studio/api/invoice/intent/{id}/approvePath idEnvelope<InvoiceIntent>
POST/v1/studio/api/invoice/intent/{id}/rejectPath id + RejectRequestEnvelope<InvoiceIntent>
POST/v1/studio/api/invoice/intent/{id}/signPath id + optional SignInvoiceRequestEnvelope<object>
POST/v1/studio/api/invoice/intent/{id}/refundPath id + RefundReviewRequestEnvelope<object>
GET/v1/studio/api/invoice/intentsInvoiceListQueryListEnvelope<InvoiceIntent>
GET/v1/studio/api/invoice/intent/{id}/logsPath idEnvelope<InvoiceLog[]>

Create an invoice

curl -X POST 'https://wallet.kryptogo.app/v1/studio/api/invoice/intent' \ -H 'Content-Type: application/json' \ -H 'X-STUDIO-API-KEY: YOUR_API_KEY' \ -H 'X-Client-ID: YOUR_CLIENT_ID' \ -d '{ "pricing_mode": "fiat", "amount": "3000.00", "currency": "TWD", "pay_token": "USDT", "chain": "arb", "origin": "https://merchant.example", "recipient_name": "Acme Buyer", "recipient_email": "buyer@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "creator": "finance-bot", "payment_terms": 30, "payment_method_type": "crypto", "payout_addresses": { "evm": "0x0000000000000000000000000000000000000000" }, "detail_items": [ { "name": "Consulting service", "quantity": 1, "unit_price": 3000, "tax": 0 } ], "order_data": { "external_invoice_id": "INV-2026-001" } }'

Invoice request schemas

InvoiceCreateRequest

Required fields: pricing_mode, amount, pay_token, chain, origin, recipient_name, recipient_email, organization_name, organization_email, creator, payment_terms, detail_items.

{ "client_id": "YOUR_CLIENT_ID", "pricing_mode": "fiat", "amount": "3000.00", "currency": "TWD", "pay_token": "USDT", "chain": "arb", "origin": "https://merchant.example", "order_data": { "external_invoice_id": "INV-2026-001" }, "callback_url": "https://merchant.example/kg-callback", "group_key": "merchant-batch-2026-06", "payout_target_address": "0x0000000000000000000000000000000000000000", "payout_addresses": { "evm": "0x0000000000000000000000000000000000000000", "sol": "SOLANA_ADDRESS", "tron": "TRON_ADDRESS" }, "payment_deadline": 1782096000, "swap_enabled": true, "use_fixed_stablecoin_rate": false, "recipient_name": "Acme Buyer", "recipient_email": "buyer@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "description": "June invoice", "attachment": { "file_id": "file_abc123" }, "creator": "finance-bot", "payment_terms": 30, "invoice_issue_date": "2026-06-22", "payment_method_type": "crypto", "allow_any_chain": false, "allow_any_token": false, "bank_account_id": 123, "detail_items": [ { "name": "Consulting service", "quantity": 1, "unit_price": 3000, "tax": 0 } ] }
FieldTypeRequiredNotes
client_idstringNoOptional body compatibility field. If present, must match X-Client-ID.
pricing_modefiat | cryptoYesPrice input mode.
amountstringYesAmount in currency for fiat mode or crypto amount for crypto mode.
currencyTWD | USDNoFiat currency.
pay_tokenUSDC | USDTYesAccepted payment token.
chainstringYesPayment chain id, for example arb.
originstringYesMerchant origin URL.
order_dataobjectNoArbitrary merchant metadata.
callback_urlstringNoWebhook callback URL.
group_keystringNoMerchant grouping key.
payout_target_addressstringNoLegacy single payout address.
payout_addressesobjectNoChain-to-address map, for example evm, sol, tron.
payment_deadlineintegerNoUnix timestamp in seconds.
swap_enabledbooleanNoWhether swap is enabled.
use_fixed_stablecoin_ratebooleanNoWhether to use a fixed stablecoin rate.
recipient_namestringYesInvoice recipient contact name.
recipient_emailstringYesInvoice recipient email.
organization_namestringYesRecipient organization name.
organization_emailstringYesRecipient organization email.
descriptionstringNoInvoice description.
attachmentobjectNoAttachment metadata.
creatorstringYesCreator display name or external actor id.
payment_termsintegerYesDays until due; 0 means due on receipt.
invoice_issue_datestringNoISO-8601 timestamp or YYYY-MM-DD.
payment_method_typecrypto | fiatNoSettlement method type.
allow_any_chainbooleanNoAllow payer to choose any supported chain.
allow_any_tokenbooleanNoAllow payer to choose any supported token.
bank_account_idintegerNoBank account id for fiat settlement.
detail_itemsInvoiceDetailItem[]YesLine items.

InvoiceDetailItem

Required fields: name, quantity, unit_price.

{ "name": "Consulting service", "quantity": 1, "unit_price": 3000, "tax": 0 }
FieldTypeRequiredNotes
namestringYesLine item name.
quantitynumberYesLine item quantity.
unit_pricenumberYesUnit price.
taxnumberNoPer-line tax amount, not a percentage rate.

InvoiceUpdateRequest

All fields are optional.

{ "recipient_name": "Acme Buyer", "recipient_email": "buyer@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "description": "Updated invoice description", "attachment": { "file_id": "file_abc123" }, "reviewer": "finance-manager@example.com", "approve_time": "2026-06-22T12:00:00Z", "invoice_issue_date": "2026-06-22", "payment_terms": 30, "payment_method_type": "crypto", "bank_account_id": 123, "payout_target_address": "0x0000000000000000000000000000000000000000", "payout_target_sol_address": "SOLANA_ADDRESS", "payout_target_tron_address": "TRON_ADDRESS", "chain": "arb", "pay_token": "USDT", "allow_any_chain": false, "allow_any_token": false, "payout_addresses": { "evm": "0x0000000000000000000000000000000000000000" }, "detail_items": [ { "name": "Consulting service", "quantity": 1, "unit_price": 3000, "tax": 0 } ] }

CancelRequest

{ "reason": "Cancelled by initiator" }

RejectRequest

Required fields: reason.

{ "reason": "Recipient information does not match our records." }

SignInvoiceRequest

All fields are optional. refund_address is required when the invoice payment is overpaid and the sign action must also create a refund.

{ "refund_address": "0x0000000000000000000000000000000000000000", "refund_reason": "Overpaid invoice refund", "refund_attachments": ["file_abc123"] }

RefundReviewRequest

Required fields: refund_address, refund_reason, refund_attachments.

{ "refund_address": "0x0000000000000000000000000000000000000000", "refund_reason": "Customer requested refund", "refund_attachments": ["file_abc123"] }

InvoiceListQuery

GET /v1/studio/api/invoice/intents?page=1&page_size=20&status=approval_pending
QueryTypeNotes
pageintegerDefault 1.
page_sizeintegerDefault 20, maximum 100.
statusstringExact invoice status.
status_categorystringStatus group.
settlement_typecrypto | fiatSettlement type.
recipient_emailstringRecipient email filter.
invoice_idstringInvoice id filter.
payment_intent_idstringPayment intent id filter.
searchstringFree-text search.
created_afterstringISO date-time lower bound.
created_beforestringISO date-time upper bound.

Payout endpoints

MethodEndpointRequestSuccess response
POST/v1/studio/api/payout/intentPayoutCreateRequestEnvelope<PayoutIntent>
GET/v1/studio/api/payout/intent/{id}Path idEnvelope<PayoutIntent>
PUT/v1/studio/api/payout/intent/{id}Path id + PayoutUpdateRequestEnvelope<PayoutIntent>
POST/v1/studio/api/payout/intent/{id}/approvePath idEnvelope<PayoutIntent>
POST/v1/studio/api/payout/intent/{id}/rejectPath id + RejectRequestEnvelope<PayoutIntent>
POST/v1/studio/api/payout/intent/{id}/refundPath id + RefundReviewRequestEnvelope<PayoutIntent>
GET/v1/studio/api/payout/intentsPayoutListQueryListEnvelope<PayoutIntent>

Create a payout

curl -X POST 'https://wallet.kryptogo.app/v1/studio/api/payout/intent' \ -H 'Content-Type: application/json' \ -H 'X-STUDIO-API-KEY: YOUR_API_KEY' \ -H 'X-Client-ID: YOUR_CLIENT_ID' \ -d '{ "pricing_mode": "fiat", "amount": "100.00", "currency": "USD", "pay_token": "USDT", "chain": "arb", "origin": "https://merchant.example", "exact_out_amount": "100.00", "recipient_name": "Jane Receiver", "recipient_email": "receiver@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "creator": "payout-bot", "recipient_type": "individual", "recipient_uid": "recipient-user-id", "order_data": { "external_payout_id": "PO-2026-001" } }'

Payout request schemas

PayoutCreateRequest

Required fields: pricing_mode, amount, pay_token, chain, origin, exact_out_amount, recipient_name, recipient_email, organization_name, organization_email, creator.

{ "client_id": "YOUR_CLIENT_ID", "pricing_mode": "fiat", "amount": "100.00", "currency": "USD", "pay_token": "USDT", "chain": "arb", "origin": "https://merchant.example", "order_data": { "external_payout_id": "PO-2026-001" }, "callback_url": "https://merchant.example/kg-callback", "group_key": "merchant-batch-2026-06", "payout_target_address": "0x0000000000000000000000000000000000000000", "payment_deadline": 1782096000, "exact_out_amount": "100.00", "swap_enabled": true, "recipient_name": "Jane Receiver", "recipient_email": "receiver@example.com", "recipient_account_email": "receiver-account@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "description": "June supplier payout", "attachment": { "file_id": "file_abc123" }, "creator": "payout-bot", "recipient_type": "individual", "recipient_uid": "recipient-user-id", "recipient_org_id": 123, "recipient_phone": "+886900000000" }
FieldTypeRequiredNotes
client_idstringNoOptional body compatibility field. If present, must match X-Client-ID.
pricing_modefiat | cryptoYesPrice input mode.
amountstringYesGross payout amount.
currencyTWD | USDNoFiat currency.
pay_tokenUSDC | USDTYesToken used for payout funding.
chainstringYesPayment chain id, for example arb.
originstringYesMerchant origin URL.
order_dataobjectNoArbitrary merchant metadata.
callback_urlstringNoWebhook callback URL.
group_keystringNoMerchant grouping key.
payout_target_addressstringNoTarget payout address.
payment_deadlineintegerNoUnix timestamp in seconds.
exact_out_amountstringYesNet amount the recipient should receive.
swap_enabledbooleanNoWhether swap is enabled.
recipient_namestringYesRecipient contact name.
recipient_emailstringYesRecipient email.
recipient_account_emailstringNoRecipient account email.
organization_namestringYesRecipient organization name.
organization_emailstringYesRecipient organization email.
descriptionstringNoPayout description.
attachmentobjectNoAttachment metadata.
creatorstringYesCreator display name or external actor id.
recipient_typeindividual | organizationNoRecipient type.
recipient_uidstringNoKryptoGO user id.
recipient_org_idintegerNoKryptoGO organization id.
recipient_phonestringNoRecipient phone number.

PayoutUpdateRequest

All fields are optional.

{ "recipient_name": "Jane Receiver", "recipient_email": "receiver@example.com", "recipient_account_email": "receiver-account@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "description": "Updated payout description", "attachment": { "file_id": "file_abc123" }, "exact_out_amount": "100.00", "chain": "arb", "pay_token": "USDT", "payout_target_address": "0x0000000000000000000000000000000000000000", "recipient_type": "individual", "recipient_uid": "recipient-user-id", "recipient_org_id": 123, "recipient_phone": "+886900000000" }

PayoutListQuery

GET /v1/studio/api/payout/intents?page=1&page_size=20&status=approval_pending
QueryTypeNotes
pageintegerDefault 1.
page_sizeintegerDefault 20, maximum 100.
payout_idstringPayout id filter.
payment_intent_idstringPayment intent id filter.
creatorstringCreator filter.
statusstringExact payout status.
status_categorystringStatus group.
settlement_typecrypto | fiatSettlement type.
searchstringFree-text search.

Response schemas

All successful responses use a KryptoGO envelope.

Envelope<T>

{ "code": 0, "data": {} }

ListEnvelope<T>

{ "code": 0, "data": [], "paging": { "page_number": 1, "page_size": 20, "total_count": 0 }, "counts": {} }

InvoiceIntent

The invoice create, get, update, cancel, approve, and reject endpoints return Envelope<InvoiceIntent>.

{ "code": 0, "data": { "id": "inv_abc123", "invoice_id": "INV-2026-001", "payment_intent": { "payment_intent_id": "pi_abc123", "client_id": "YOUR_CLIENT_ID", "org_id": 123, "pricing_mode": "fiat", "payment_chain_id": "arb", "payment_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "payer_address": null, "token_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "symbol": "USDT", "decimals": 6, "crypto_amount": "9.23", "fiat_amount": "3000.00", "fiat_currency": "TWD", "payment_deadline": 1782096000, "status": "awaiting_approval", "payment_tx_hash": null, "payment_tx_timestamp": null, "aggregation_tx_hash": null, "refund_tx_hash": null, "received_crypto_amount": null, "aggregated_crypto_amount": null, "refund_crypto_amount": null, "order_data": { "external_invoice_id": "INV-2026-001" }, "callback_url": "https://merchant.example/kg-callback", "group_key": "merchant-batch-2026-06", "kg_deep_link": "https://kryptogo.page.link/send?...", "payment_method_type": "crypto", "swap_enabled": true, "payout_target_address": "0x0000000000000000000000000000000000000000", "payout_target_sol_address": null, "payout_target_tron_address": null, "payout_addresses": { "evm": "0x0000000000000000000000000000000000000000" }, "exact_out_amount": null, "kg_fee_amount": null, "aggregation_tx_timestamp": null, "finalized_timestamp": null, "partial_refund_tx_hash": null, "partial_refund_amount": null, "partial_refund_address": null, "crypto_price": null, "target_chain_id": null, "target_token_address": null, "bank_account_id": null, "kya_risk": null, "large_transaction_risk": null, "kya_risk_address": null, "kya_risk_counter_party": null, "transaction_frequency_risk": null, "total_weighted_risk_score": null, "quick_in_out_risk": null, "dormant_account_risk": null, "volume_spike_risk": null, "structuring_risk": null, "kya_accumulation_risk": null, "business_pattern_risk": null, "kya_record": {} }, "status": "approval_pending", "recipient_name": "Acme Buyer", "recipient_email": "buyer@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "payment_terms": 30, "detail_items": [ { "name": "Consulting service", "quantity": 1, "unit_price": 3000, "tax": 0 } ] } }

InvoiceIntent may include additional fields as Studio adds workflow metadata. Treat unknown fields as additive.

FieldTypeNotes
idstringInvoice intent id.
invoice_idstringHuman-readable invoice id.
payment_intentPaymentIntentNested payment intent.
statusstringInvoice workflow status.
recipient_namestringRecipient contact name.
recipient_emailstringRecipient email.
organization_namestringRecipient organization name.
organization_emailstringRecipient organization email.
payment_termsintegerPayment terms in days.
detail_itemsobject[]Invoice line items.

PayoutIntent

The payout create, get, update, approve, reject, and refund endpoints return Envelope<PayoutIntent>.

{ "code": 0, "data": { "id": "payout_abc123", "payout_id": "PO-2026-001", "payment_intent": { "payment_intent_id": "pi_abc123", "client_id": "YOUR_CLIENT_ID", "org_id": 123, "pricing_mode": "fiat", "payment_chain_id": "arb", "payment_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "payer_address": null, "token_address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "symbol": "USDT", "decimals": 6, "crypto_amount": "100.00", "fiat_amount": "100.00", "fiat_currency": "USD", "payment_deadline": 1782096000, "status": "awaiting_approval", "payment_tx_hash": null, "payment_tx_timestamp": null, "aggregation_tx_hash": null, "refund_tx_hash": null, "received_crypto_amount": null, "aggregated_crypto_amount": null, "refund_crypto_amount": null, "order_data": { "external_payout_id": "PO-2026-001" }, "callback_url": "https://merchant.example/kg-callback", "group_key": "merchant-batch-2026-06", "kg_deep_link": "https://kryptogo.page.link/send?...", "payment_method_type": "crypto", "swap_enabled": true, "payout_target_address": "0x0000000000000000000000000000000000000000", "payout_target_sol_address": null, "payout_target_tron_address": null, "payout_addresses": {}, "exact_out_amount": "100.00", "kg_fee_amount": null, "aggregation_tx_timestamp": null, "finalized_timestamp": null, "partial_refund_tx_hash": null, "partial_refund_amount": null, "partial_refund_address": null, "crypto_price": null, "target_chain_id": null, "target_token_address": null, "bank_account_id": null, "kya_risk": null, "large_transaction_risk": null, "kya_risk_address": null, "kya_risk_counter_party": null, "transaction_frequency_risk": null, "total_weighted_risk_score": null, "quick_in_out_risk": null, "dormant_account_risk": null, "volume_spike_risk": null, "structuring_risk": null, "kya_accumulation_risk": null, "business_pattern_risk": null, "kya_record": {} }, "status": "approval_pending", "recipient_name": "Jane Receiver", "recipient_email": "receiver@example.com", "organization_name": "Merchant Ltd.", "organization_email": "finance@merchant.example", "exact_out_amount": "100.00" } }

PayoutIntent may include additional fields as Studio adds workflow metadata. Treat unknown fields as additive.

FieldTypeNotes
idstringPayout intent id.
payout_idstringHuman-readable payout id.
payment_intentPaymentIntentNested payment intent.
statusstringPayout workflow status.
recipient_namestringRecipient contact name.
recipient_emailstringRecipient email.
organization_namestringRecipient organization name.
organization_emailstringRecipient organization email.
exact_out_amountstringNet amount the recipient should receive.

PaymentIntent

InvoiceIntent.payment_intent and PayoutIntent.payment_intent share the same nested format.

FieldTypeNotes
payment_intent_idstringPayment intent id.
client_idstringStudio OAuth client id.
org_idintegerOrganization id.
pricing_modefiat | cryptoPricing mode.
payment_chain_idstringPayment chain id.
payment_addressstringGenerated payment address.
payer_addressstring | nullPayer address after payment.
token_addressstringToken contract address.
symbolstringToken symbol.
decimalsintegerToken decimals.
crypto_amountstringCrypto amount.
fiat_amountstring | nullFiat amount.
fiat_currencyTWD | USD | nullFiat currency.
payment_deadlineintegerUnix timestamp in seconds.
statusstringPayment status: pending, success, expired, insufficient_not_refunded, insufficient_refunded, cancelled, aml_hold, awaiting_approval, manual_review, or refunded.
payment_tx_hashstring | nullPayment transaction hash.
payment_tx_timestampinteger | nullPayment confirmation timestamp.
aggregation_tx_hashstring | nullAggregation transaction hash.
refund_tx_hashstring | nullRefund transaction hash.
received_crypto_amountstring | nullReceived crypto amount.
aggregated_crypto_amountstring | nullAggregated crypto amount.
refund_crypto_amountstring | nullRefunded crypto amount.
order_dataobjectMerchant metadata.
callback_urlstring | nullWebhook callback URL.
group_keystringMerchant grouping key.
kg_deep_linkstring | nullKryptoGO payment deep link.
payment_method_typestringPayment method type.
swap_enabledbooleanWhether swap is enabled.
payout_target_addressstring | nullEVM payout target address.
payout_target_sol_addressstring | nullSolana payout target address.
payout_target_tron_addressstring | nullTron payout target address.
payout_addressesobjectChain-to-address map.
exact_out_amountstring | nullNet payout amount.
kg_fee_amountstring | nullKryptoGO fee amount.
aggregation_tx_timestampinteger | nullAggregation timestamp.
finalized_timestampinteger | nullFinalized timestamp.
partial_refund_tx_hashstring | nullPartial refund transaction hash.
partial_refund_amountstring | nullPartial refund amount.
partial_refund_addressstring | nullPartial refund address.
crypto_pricestring | nullCrypto price used for conversion.
target_chain_idstring | nullTarget chain id.
target_token_addressstring | nullTarget token address.
bank_account_idinteger | nullBank account id.
kya_riskstring | nullKYA risk value.
large_transaction_riskstring | nullLarge transaction risk value.
kya_risk_addressstring | nullAddress risk value.
kya_risk_counter_partystring | nullCounterparty risk value.
transaction_frequency_riskstring | nullFrequency risk value.
total_weighted_risk_scorestring | nullTotal weighted risk score.
quick_in_out_riskstring | nullQuick in/out risk value.
dormant_account_riskstring | nullDormant account risk value.
volume_spike_riskstring | nullVolume spike risk value.
structuring_riskstring | nullStructuring risk value.
kya_accumulation_riskstring | nullAccumulation risk value.
business_pattern_riskstring | nullBusiness pattern risk value.
kya_recordobjectKYA record details.

InvoiceLog

{ "id": 123, "invoice_id": "inv_abc123", "from_status": "approval_pending", "to_status": "approved", "operator_uid": "user_abc123", "reason": "Approved by finance", "created_at": "2026-06-22T12:00:00Z" }
FieldTypeNotes
idintegerLog id.
invoice_idstringInvoice intent id.
from_statusstringPrevious status.
to_statusstringNew status.
operator_uidstringOperator user id.
reasonstringStatus transition reason.
created_atstringISO date-time.
Last updated on