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). Defaults to 1 if not sent. 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 <= 18
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

​
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"

​
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"