Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Creates a single sales transaction. To create several transactions at once, see the Batch upload page.

POST https://api.rapidchargeback.com/api/v1/transactions
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

The company must have Prevention or Dispute active. Without either of them, the response is 403 PRODUCT_NOT_ACTIVE and the transaction is not created. See Who sends transactions.


FieldTypeDescription
merchant_id or merchant_refstringSend exactly one: merchant_id (the merchant’s UUID at Rapid, must belong to your company) or merchant_ref (the seller’s ID in your system, up to 100 characters, for channels/platforms with several sellers). If merchant_ref is unknown, the merchant is created automatically with merchant_name (optional, up to 255 characters; ignored when the merchant already exists). Sending both → 422 VALIDATION_ERROR. Your merchants and their merchant_id are in List merchants.
external_idstringTransaction ID in the source system
amountnumberTransaction amount (must be positive)
currencystringISO 4217 code with 3 uppercase letters (e.g. USD, BRL)
transaction_datestringTransaction date in ISO 8601 format (e.g. 2026-04-01T15:30:00Z)
card_last4stringLast 4 digits of the card (exactly 4 numeric digits)
itemsarrayAt least 1 item (see the item fields below)
FieldTypeDescription
product_descriptionstringProduct description (up to 1000 characters; above that the request fails)
unit_pricenumberUnit price
FieldTypeDescription
product_namestringProduct name
quantitynumberQuantity
unit_of_measurestringUnit of measure
categorystringProduct category

FieldTypeDescription
external_sourcestringSource system (default: custom)
order_numberstringOrder number
transaction_idstringTransaction ID in the payment gateway. See the note below
arnstringAcquirer Reference Number
banknet_refstringBanknet reference (Mastercard)
auth_codestringAuthorization code
networkstringCard network: visa, mastercard, amex, discover, other
card_binstringCard BIN (6 to 8 numeric digits)
ip_addressstringBuyer’s IP address
clearing_datetimestringClearing date (ISO 8601)
mccstringMerchant Category Code
ecistringElectronic Commerce Indicator
pos_entry_modestringPOS entry mode
descriptorstringBilling descriptor
correlation_idstringCorrelation ID
device_idstringDevice ID (min. 15 characters)
device_fingerprintstringDevice fingerprint (min. 20 characters)
customerobjectBuyer data (see below)
addressesarrayShipping and/or billing addresses (see below)
paymentsarrayPayment data (see below)
refundsarrayRefund data (see below)

Every text field has a ceiling. Above it the response is 422 VALIDATION_ERROR naming the field, never a server error.

LimitFields
1000product_description
255descriptor, merchant_name, product_name, device_fingerprint, street, reason (refund)
200billing_name
100external_id, order_number, transaction_id, arn, banknet_ref, correlation_id, merchant_ref, device_id, first_name, last_name, city, state, category
64method_masked, reference_number
45ip_address (fits IPv6)
50external_source, auth_code, account_id
32unit_of_measure
30phone, postal_code, wallet_indicator
20number (address)
16payment_type
10mcc, pos_entry_mode
7card_expiry
5eci
2cvv2_presence_indicator, avs_result

email follows the 255 limit and must have a valid format. currency, card_bin, card_last4, country and network have a fixed format, described in the fields table.

It is optional, but fill it in whenever the charge went through a payment gateway: this is the field Rapid uses to link a future chargeback to the transaction. Send the charge identifier in the gateway, not your order number (that one is order_number).

If you use a gateway whose disputes reach Rapid and the field is empty, the chargeback is still received, but with no associated transaction: no history, no attached evidence and no authentication data, which is exactly the defense material. An equivalent alternative: send external_source with the gateway name and external_id with the charge id.

If the transaction arrives after the dispute (or you fill in the identifier later by updating the transaction), Rapid links the two by the same identifier while the dispute is open, and the defense becomes available from then on.


FieldTypeDescription
first_namestringFirst name
last_namestringLast name
emailstringEmail (valid format)
billing_namestringName on the card
account_idstringBuyer’s account ID in your system
phonestringPhone

address object (inside the addresses array)

Section titled “address object (inside the addresses array)”
FieldTypeRequiredDescription
typestringYesshipping or billing
streetstringNoStreet
numberstringNoNumber
citystringNoCity
statestringNoState/Region
postal_codestringNoPostal code
countrystringNoISO 3166-1 country code, 2 or 3 uppercase letters (BR/BRA, US/USA). Alpha-3 recommended.

Payment authentication fields (root, all optional)

Section titled “Payment authentication fields (root, all optional)”

Inputs for fraud protection and 3-DS. The more you fill in, the stronger the deflection and the defense.

FieldTypeDescription
cvv2_presence_indicatorstringCVV2 presence indicator in the authorization
cvv2_resultstringCVV2 check result: M, N, P, S, U or Y, as it came in the authorization response
avs_resultstringAVS result (address verification)
cardholder_verification_approvedboolean3-DS/cardholder verification approved
authentication_response_typestring3-DS authentication response type: attempt (attempt) or confirm (authentication confirmed)
wallet_indicatorstringDigital wallet used (e.g. Apple Pay, Google Pay)

Buyer account (inside customer, all optional)

Section titled “Buyer account (inside customer, all optional)”

They say whether the purchase was made by a known account, and since when it exists. They are the strongest defense material in a fraud dispute: a buyer with an old account who was logged in is hard to dispute as “I do not recognize it”.

FieldTypeDescription
registered_atstring (ISO 8601)When the buyer’s account was created in your system
registered_at_sourcestringWhere registered_at comes from: merchant_api (account record in your system) or client_declared (your statement, without that record)
account_authenticatedbooleanThe buyer was logged into the account when purchasing
account_authenticated_sourcestringHow you know it: per_account (verified in this purchase) or onboarding_flag (your store’s rule, for example, every purchase requires login)
account_authenticated_atstring (ISO 8601)When the login happened
auth_methodstringHow the buyer logged in: password, otp, 2fa, biometric, oauth or other
account_source_methodstringWhere the account data comes from: merchant_api or client_declared
checkout_typestringHow the purchase was made: guest (no account), authenticated (existing account, logged in) or registered_at_checkout (account created during the purchase)

A value outside the lists responds 422 VALIDATION_ERROR.

FieldTypeDescription
payment_typestringPayment type (credit, debit, pix, etc.)
method_maskedstringMasked number
matched_paymentbooleanWhether this payment was the one used (default: true)
card_binstringBIN (6-8 digits)
card_last4stringLast 4 digits (4 numeric digits)
installmentsintegerNumber of installments
card_expirystringExpiry (MM/YYYY)
FieldTypeRequiredDescription
amountnumberYesRefund amount (positive)
currencystringYesCurrency (3 uppercase letters, ISO 4217)
reference_numberstringNoRefund identifier
reasonstringNoRefund reason
refund_datetimestringNoRefund date (ISO 8601)

  • transaction_date must be in ISO 8601 with timezone
  • currency must be an ISO 4217 code (3 uppercase letters)
  • amount must be greater than zero
  • card_last4 must have exactly 4 numeric digits
  • card_bin must have 6 to 8 numeric digits
  • device_id must have at least 15 characters
  • device_fingerprint must have at least 20 characters
  • The external_source + external_id combination cannot duplicate an existing transaction of your company

The API returns notices (without blocking creation) when important optional fields are missing:

WhenNotice
No card_bincard_bin missing: reduces match accuracy
No order_numberorder_number missing: recommended to identify the order in dispute responses
No ip_address, device_id and device_fingerprintip_address, device_id and device_fingerprint missing: recommended, fraud protection relies on them

One of the three identifiers is enough to clear the last notice: the IP is not required. And there is no address notice on purpose: whoever sells digital goods should not send a shipping address (see fraud protection).

The warnings key only shows up in the response when there is at least one notice. Do not count on warnings: [].


The credentials come from environment variables (RAPID_CLIENT_ID and RAPID_CLIENT_SECRET), never written in the code.

Terminal window
curl -X POST https://api.rapidchargeback.com/api/v1/transactions \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "00000000-0000-0000-0000-000000000001",
"external_source": "shopify",
"external_id": "TXN-2026-001",
"transaction_date": "2026-04-01T15:30:00Z",
"amount": 150.00,
"currency": "USD",
"card_last4": "4242",
"card_bin": "424242",
"order_number": "ORD-001",
"auth_code": "AUTH999",
"network": "visa",
"descriptor": "LOJA EXEMPLO",
"ip_address": "203.0.113.10",
"items": [
{
"product_description": "Assinatura Premium - Mensal",
"product_name": "Plano Premium",
"quantity": 1,
"unit_price": 150.00
}
],
"customer": {
"first_name": "João",
"last_name": "Silva",
"email": "joao@exemplo.com"
},
"addresses": [
{
"type": "shipping",
"street": "Rua das Flores",
"number": "123",
"city": "São Paulo",
"state": "SP",
"postal_code": "01001000",
"country": "BRA"
}
]
}'

{
"data": {
"id": "00000000-0000-0000-0000-000000000042",
"company_id": "...",
"merchant_id": "00000000-0000-0000-0000-000000000001",
"external_id": "TXN-2026-001",
"amount": 150.00,
"currency": "USD",
"transaction_date": "2026-04-01T15:30:00.000Z",
"card_last4": "4242",
"created_at": "2026-04-01T15:31:00.000Z",
"transaction_items": [...],
"transaction_customers": [...],
"transaction_addresses": [...]
}
}
{
"error": {
"code": "TRANSACTION_DUPLICATE",
"message": "Transaction already exists"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "card_last4 must be exactly 4 digits"
}
}

The company has neither Prevention nor Dispute active. Body validation comes first: an invalid body responds 422 even in this case.

{
"error": {
"code": "PRODUCT_NOT_ACTIVE",
"message": "Transactions require an active Prevention or Dispute product"
}
}