Skip to main content
POST
Create a new transaction for a specific merchant

Authorizations

​
x-api-key
string
header
required

Company API key for authentication

Path Parameters

​
merchantId
string
required

The merchant ID

Body

application/json

Schema for creating a new transaction.

​
request_id
string
required

Unique request ID for this transaction (used for idempotency)

Minimum string length: 1
Example:

"request-123"

​
amount
integer
required

Transaction amount in cents (e.g., 10050 = R$ 100,50)

Required range: 1 <= x <= 1500000000
Example:

10050

​
capture_method
enum<string>
required

Transaction capture method:

  • EMV: Chip card
  • MAGSTRIPE: Magnetic stripe
  • ECOMMERCE: Online transaction
  • CONTACTLESS_ICC: Contactless payment
Available options:
EMV,
MAGSTRIPE,
ECOMMERCE,
CONTACTLESS_ICC
Example:

"ECOMMERCE"

​
payment_method
enum<string>
required

Payment method:

  • CREDIT_CARD: Credit card payment
  • DEBIT_CARD: Debit card payment
  • PIX: Instant payment
  • BOLEPIX: Hybrid Boleto + PIX payment
Available options:
CREDIT_CARD,
DEBIT_CARD,
PIX,
BOLEPIX
Example:

"PIX"

​
provider
enum<string>

Payment provider that processes the transaction. Optional.

When omitted, Rinne picks the provider for you among the ones your company is enabled on for this payment_method and capture_method:

  • the provider configured for your company, your organization, or Rinne-wide, in that order, when your company is enabled on it;
  • otherwise, the only provider your company is enabled on for this combination.

When your company is enabled on more than one provider for this combination and none is configured, the request is rejected with a 400 whose issue is REQUIRED on provider; send provider in that case. The provider that processed the transaction is always returned in the response.

Available options:
CELCOIN,
CAPPTA
Example:

"CELCOIN"

​
currency
enum<string>
default:BRL

Transaction currency (defaults to BRL)

Available options:
BRL
Example:

"BRL"

​
installments
integer
default:1

Number of installments (1-18, or 1-21 when the transaction is processed on a gateway-mode affiliation). Defaults to 1 if not sent. 19-21 on any other affiliation answers 400 with installments OUT_OF_RANGE (min 1, max 18); above 21 the request fails schema validation on every affiliation. Only CREDIT_CARD supports more than 1 installment — it must be 1 when payment_method is DEBIT_CARD, PIX, or BOLEPIX.

Required range: 1 <= x <= 21
Example:

1

​
pix_data
object

PIX-specific data. Required when payment_method is PIX. When due_date is provided: consumer is required (full_name, document_number, document_type) and use expiration_in_days_after_due_date (do not send expiration_in_seconds). When due_date is NOT provided: use expiration_in_seconds (do not send expiration_in_days_after_due_date).

Example:
​
bolepix_data
object

BOLEPIX-specific data. Required when payment_method is BOLEPIX. When payment_method is BOLEPIX, consumer is required with full_name, document_type, document_number, and full address including address.street_number. Each address field sent to the provider must contain at least one letter or digit — a punctuation-only value such as "." is rejected.

Example:
​
card_data
object

Card payment data. Required for CREDIT_CARD and DEBIT_CARD payment methods.

Example:
​
three_d_secure_session_id
string<uuid>

ID of an authenticated 3DS session to use for this transaction (session-first flow). When provided, the cryptogram and ECI from the session are injected into the card data. The session must be authenticated (auth_status=AUTHENTICATED), not expired, not already consumed, and match the transaction's company, amount, and currency.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
require_3ds
boolean

Card transactions only. When true, the transaction is created directly in AWAITING_3DS and is not sent to the provider until /authenticate is called with an authenticated 3DS session.

Example:

true

​
refuse_on_challenge
boolean

Card transactions only. When true, challenge-triggered paths are refused (REFUSED) instead of transitioning to AWAITING_3DS. Cannot be true together with require_3ds.

Example:

false

​
consumer
object

Optional consumer/customer information. Required with full_name, document_number, and document_type when pix_data.due_date is provided. When payment_method is BOLEPIX, consumer is required and must include full_name, document_type, document_number, and full address including address.street_number. Each address field must contain at least one letter or digit.

Example:
​
metadata
object

Optional additional metadata (key-value pairs)

Example:
​
split_rules
object[]

Optional split rules for transaction revenue sharing.

Important rules:

  • Cannot mix amount and percentage in same transaction
  • If using amounts: sum must equal transaction amount
  • If using percentages: sum must equal 100%
Example:
​
soft_descriptor
string

Card transactions only. Text printed on the cardholder's statement after the merchant's name, as ; the merchant's name gives up characters so the text fits. Accented letters fold to their base letter; letters without one, letters from other scripts, spaces and any character other than digits and % $ , . / & ( ) + = < > - are dropped, and the result is upper-cased. Nine characters of the result fit; the rest is cut. The whole line is at most 22 characters, so the merchant's name is shortened to make room. The merchant's name is its short name, or its legal name when it has none. When omitted, or when the cut leaves no letter or digit, the line ends with the merchant's name. The value itself is stored and returned as sent; an empty string is rejected.

Minimum string length: 1
Example:

"MYSTORE"

​
serial_number
string

Optional terminal serial number

Example:

"12345678"

​
nsu
string

Optional Network Sequential Number

Example:

"000123"

​
fee_policy_id
string

Optional fee policy ID to use for this transaction. If provided, this takes priority over the company's default fee policy. The fee policy must belong to the same organization as the company.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Transaction created successfully

Transaction data returned by the API

​
id
string
required

Transaction unique identifier

Example:

"tx_123456789"

​
provider
enum<string>
required

Payment provider

Available options:
CELCOIN,
RINNE,
CAPPTA
Example:

"CELCOIN"

​
affiliation_id
string
required

Affiliation ID for this transaction

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

​
request_id
string
required

Unique request ID for this transaction used for idempotency

Example:

"request-123"

​
mcc
string
required

Merchant Category Code

Example:

"5411"

​
amount
integer
required

Transaction amount in cents

Example:

10050

​
currency
enum<string>
required

Transaction currency

Available options:
BRL
Example:

"BRL"

​
pricing
object
required

Transaction pricing information

​
status
enum<string>
required

Transaction status

Available options:
PROCESSING,
AUTHORIZED,
APPROVED,
REFUNDED,
PARTIALLY_REFUNDED,
PENDING_REFUND,
CHARGEDBACK,
WAITING_PAYMENT,
AWAITING_3DS,
RISK_ANALYSIS,
REFUSED,
FAILED,
EXPIRED,
PENDING_CANCELLATION,
CANCELLED
Example:

"APPROVED"

​
capture_method
enum<string>
required

Transaction capture method

Available options:
EMV,
MAGSTRIPE,
ECOMMERCE,
CONTACTLESS_ICC
Example:

"EMV"

​
installments
integer | null
required

Number of installments

Example:

1

​
payment_method
enum<string>
required

Payment method

Available options:
CREDIT_CARD,
DEBIT_CARD,
PIX,
BOLEPIX
Example:

"PIX"

​
automatic_anticipation
boolean
required

Whether this transaction was automatically anticipated at creation time. Set to true when the affiliation's anticipation_type is AUTOMATIC; false otherwise.

Example:

false

​
anticipation_days
integer
required

Automatic-anticipation horizon in days (D+N), copied from the affiliation at creation and immutable after. 0 when automatic_anticipation is false. Available to fee and cost policy rule conditions as transaction.anticipation_days. A transaction created before this field existed reports the affiliation's current horizon when automatic_anticipation is true and 0 otherwise, until a one-time backfill stores its value; its card refund window is the next-business-day one until then.

Required range: x >= 0
Example:

1

​
origin
enum<string>
required

Where the transaction originated. INTERNAL: created through the Rinne API. EXTERNAL: originated outside the platform and registered from a provider event, such as an inbound Pix sent directly to a Pix key or a POS (card machine) transaction.

Available options:
INTERNAL,
EXTERNAL
Example:

"INTERNAL"

​
company_id
string
required

Company ID that owns this transaction

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

​
company_document_type
enum<string>
required

Document type of the company that owns this transaction (the receiver).

Available options:
CPF,
CNPJ
Example:

"CNPJ"

​
company_document_number
string
required

Document number of the company that owns this transaction (the receiver), without formatting: CPF (11 digits) or CNPJ (14 characters, alphanumeric CNPJ supported).

Example:

"12345678000195"

​
pix_payer
object | null
required

The account holder who actually paid a PIX transaction, as reported by the payment provider when the payment is received. May differ from consumer, which is what the integrator sent at creation. null until the payment is received, and for every other payment method. A PIX received on a Pix key without a charge carries it from creation.

​
created_at
string<date-time>
required

Transaction creation timestamp

Example:

"2023-12-01T10:00:00.000Z"

​
fee_policy_id
string | null

Fee policy ID applied to this transaction

Example:

"fee_policy_123"

​
cost_policy_id
string | null

Cost policy ID applied to this transaction

Example:

"cost_policy_123"

​
approved_amount
integer | null

Approved amount in cents

Example:

10050

​
refunded_amount
integer | null

Total amount refunded in cents (sum of completed refunds)

Example:

0

​
three_d_secure_session_id
string<uuid> | null

ID of the 3DS session linked to this transaction, if any. Set when the transaction was created with a 3DS session (session-first flow) or authenticated via the /authenticate endpoint (transaction-first flow).

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
acquirer_response_code
string | null

Acquirer response code

Example:

"00"

​
pix_data
object | null

PIX-specific data (present if payment_method is PIX)

​
bolepix_data
object | null

Bolepix-specific data (present if payment_method is BOLEPIX)

​
card_data
object | null

Card-specific data (present if payment_method is CREDIT_CARD or DEBIT_CARD)

​
soft_descriptor
string | null

The soft_descriptor sent with the create request, as sent. Null when the request had none.

Example:

"MYSTORE"

​
serial_number
string | null

Terminal serial number

Example:

"12345678"

​
nsu
string | null

Network Sequential Number

Example:

"000123"

​
metadata
object | null

Additional metadata

​
latest_refund_at
string<date-time> | null

Latest refund timestamp (for the most recent completed refund)

Example:

"2023-12-01T10:00:00.000Z"

​
status_reason
enum<string> | null

Status reason details. REVERSED indicates a failed card transaction whose charge was later found at the acquirer and reversed by reconciliation.

Available options:
PROVIDER,
ACQUIRER,
ANTIFRAUD,
INTERNAL_ERROR,
NO_ACQUIRER,
ACQUIRER_TIMEOUT,
CHALLENGE_NOT_ALLOWED,
REVERSED
Example:

"PROVIDER"

​
approved_at
string | null

Transaction approval timestamp

Example:

"2023-12-01T10:00:00.000Z"

​
company_full_name
string

Company full name

Example:

"Test Company"

​
company_name
string | null

Company name

Example:

"Test Company"

​
organization_id
string | null

Organization transaction ID (for refunds/chargebacks)

Example:

"tx_organization_123456"

​
consumer
object | null

Consumer information

​
updated_at
string<date-time> | null

Transaction last update timestamp

Example:

"2023-12-01T10:00:00.000Z"