Rinne API Documentation

Use this guide to implement CREDIT_CARD and DEBIT_CARD transactions with the Rinne Core API.

Rinne officially supports both 3DS strategies for card payments: session-first and transaction-first.

Transaction endpoints (self vs merchant)

Context	Create transaction	Authenticate pending transaction
Self (company)	`POST /v1/transactions`	`POST /v1/transactions/{id}/authenticate`
Organization on behalf of merchant	`POST /v1/merchants/{merchantId}/transactions`	`POST /v1/merchants/{merchantId}/transactions/{id}/authenticate`

Prerequisites

Active affiliation for card payments.
ECOMMERCE capture enabled for online transactions.
One unique request_id per payment attempt.
Encrypted card values from rinne-js secure components.

Do not collect raw PAN/CVC in custom inputs. Forward encrypted values from Card Element only.

Sending card data

Rinne’s API only accepts card credentials in encrypted form. The card_data.number, card_data.cvv, card_data.network_token, and card_data.cryptogram values must arrive encrypted — you can recognize encrypted values by their ev: prefix. Requests where one of these fields arrives in plain text are rejected with 400 VALIDATION_ERROR before any processing happens. These encrypted values come from the rinne-js secure components: the Card Element encrypts the card number and CVV in the customer’s browser, and the wallet elements emit network_token and cryptogram already encrypted. Raw card data never touches your servers.

Required transaction shape

string

Payment provider that processes the transaction, such as CAPPTA. Optional. When you omit it, Rinne picks the provider from the merchant’s eligible affiliations. See Provider selection.

string

required

Idempotency key for creation.

integer

required

Amount in cents.

string

required

Use ECOMMERCE for card-not-present checkout.

string

required

CREDIT_CARD or DEBIT_CARD.

object

required

Card payload for card transactions.

Card data rules

Send exactly one of card_data.number (raw card entry), card_data.network_token (wallet), or card_data.card_id (stored card).
Send number and cvv as encrypted values from rinne-js. Values that reach the API unencrypted are rejected with 400 VALIDATION_ERROR.
With number or network_token, send expiry_month (MM), expiry_year (YYYY), last_digits (the last 4 digits of the card number, exactly 4 digits), and cardholder_name as it appears on the card.
With card_id, Rinne resolves those fields from the stored card — see Example: charge a stored card.
For authenticated/tokenized flows, provide cryptogram directly or via three_d_secure_session_id injection.
For wallet tokenized flows, include wallet_type (APPLE_PAY or GOOGLE_PAY).

Do not send more than one of number, network_token, and card_id in the same request.

3DS challenge strategy flags

TransactionCreateRequest supports two optional card-only flags:

boolean

When true, card transaction creation always goes directly to AWAITING_3DS. Provider authorization is deferred until /authenticate is called with an authenticated 3DS session.

boolean

When true, any path that would require a challenge (risk-triggered or soft-decline-triggered) is refused immediately (REFUSED) instead of transitioning to AWAITING_3DS.

Why these flags are useful

Flag	Immediate status behavior	What your backend still handles	What this avoids
`require_3ds`	Always creates card transactions in `AWAITING_3DS`	Create 3DS session, complete challenge when required, and call `/authenticate`	Implementing a second session-first architecture only to enforce 3DS policy
`refuse_on_challenge`	Returns `REFUSED` with `status_reason=CHALLENGE_NOT_ALLOWED` when challenge would be required	Handle refusal/retry paths only	Implementing challenge UX and pending `AWAITING_3DS` operational queues for that scope

With require_3ds, organizations that already run transaction-first can enforce 3DS for all or selected transactions without adding a separate session-first policy path. The transaction enters AWAITING_3DS immediately, which is the status you already handle in this flow. With refuse_on_challenge, challenge-triggered flows do not enter AWAITING_3DS; they stop immediately as REFUSED, so your operation fails fast and carries no challenge-handling workload.

refuse_on_challenge changes only challenge-triggered paths. Transactions that do not require challenge continue normal provider processing.

`CHALLENGE_NOT_ALLOWED` status reason

When refuse_on_challenge is true and a challenge would be required (risk-triggered or soft-decline-triggered), transaction response uses:

status = REFUSED
status_reason = CHALLENGE_NOT_ALLOWED

require_3ds and refuse_on_challenge are mutually exclusive. Requests with both set to true must be rejected.

Policy granularity

Because these flags are part of each transaction request, you can apply policies with fine control:

Per merchant (choose behavior by merchantId in your backend routing).
Per payment flow (for example, mobile app vs web checkout).
Per transaction segment (risk tier, issuer group, customer cohort, high-value purchases).

Example: standard card transaction

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/transactions' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "CAPPTA",
    "request_id": "order-card-0001",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "installments": 1,
    "card_data": {
      "number": "ev:encrypted:card_number",
      "cvv": "ev:encrypted:cvc",
      "expiry_month": "12",
      "expiry_year": "2028",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111"
    }
  }'

Example: charge a stored card

To charge a card you stored on file, send its id as card_data.card_id in place of the card credentials. Rinne resolves the encrypted number, expiry_month, expiry_year, last_digits, brand, and cardholder_name from the stored card.

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/transactions' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "CAPPTA",
    "request_id": "order-stored-card-0001",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "installments": 1,
    "card_data": {
      "card_id": "9c1f2e3a-4b5c-4d6e-8f90-a1b2c3d4e5f6",
      "cvv": "ev:encrypted:cvc"
    }
  }'

Include cvv for customer-present payments that re-collect it, and omit it for merchant-initiated payments such as recurring charges. Everything outside card_data — installments, the 3DS challenge strategy flags, and the merchant route — behaves exactly as it does with inline card data.

Do not send number, network_token, expiry_month, expiry_year, last_digits, brand, or cardholder_name alongside card_id. The stored card supplies these fields, so sending them inline is ambiguous and is rejected with 400 VALIDATION_ERROR.

A card_id that Rinne cannot charge is rejected with 400 VALIDATION_ERROR on the card_data.card_id field, in three cases:

No such card in scope — the card doesn’t exist, was deleted, or belongs to another company. A card is only chargeable by the company that owns it.
The card isn’t active — its status is not ACTIVE.
The card has no brand — Rinne’s providers require a brand to process a transaction, so a stored card without one can’t be charged.

Example: force transaction-first 3DS

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/transactions' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "CAPPTA",
    "request_id": "order-card-0002",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "card_data": {
      "number": "ev:encrypted:card_number",
      "cvv": "ev:encrypted:cvc",
      "expiry_month": "12",
      "expiry_year": "2028",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111"
    },
    "require_3ds": true
  }'

Example response

{
  "id": "tx_123456789",
  "status": "AWAITING_3DS",
  "amount": 25990,
  "currency": "BRL"
}

Example: fail fast when challenge is not allowed

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/transactions' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "CAPPTA",
    "request_id": "order-card-0003",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "card_data": {
      "number": "ev:encrypted:card_number",
      "cvv": "ev:encrypted:cvc",
      "expiry_month": "12",
      "expiry_year": "2028",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111"
    },
    "refuse_on_challenge": true
  }'

Example response

{
  "id": "tx_123456789",
  "status": "REFUSED",
  "status_reason": "CHALLENGE_NOT_ALLOWED"
}

Card statement descriptor

Every card charge appears on the cardholder’s statement as a short line, the soft descriptor. Rinne builds that line from the merchant’s name, and you can add your own text to it per transaction, such as an order number, so the cardholder recognizes the charge instead of disputing it.

string

Card transactions only. Your text for the cardholder’s statement, printed after the merchant’s name. Send it at the top level of the create request, next to amount, not inside card_data. The transaction returns the value exactly as you sent it. An empty string is rejected with 400 VALIDATION_ERROR; omit the field when you have no text.

How Rinne composes the statement line

The statement line holds at most 22 characters, in three parts separated by *:

<facilitator>*<merchant>*<text>

<facilitator>: the identifier of the payment facilitator that processes the sale. Sales through a payment facilitator must carry it, so you cannot change or remove it. It takes 6 characters, plus 1 for its separator.
<merchant>: the merchant’s name. When name is missing or has no letter A–Z or digit once accents fold, Rinne uses the merchant’s legal name, full_name.
<text>: your soft_descriptor. When you omit it, or Rinne drops it under the rules below, the line ends at the merchant’s name.

The soft_descriptor field on an affiliation does not affect the line. Rinne applies three rules, in this order, to the merchant’s name and to your text:

Characters. Accented letters fold to their base letter (Açaí becomes ACAI) and every letter is uppercased. Rinne then removes spaces, *, letters with no base letter (such as ø and æ; ß becomes SS), letters from other scripts, and every symbol except % $ , . / & ( ) + = < > -.
Text length. Rinne keeps the first 9 characters of your text and cuts the rest without an error. If those 9 characters hold no letter or digit, Rinne drops your text.
Merchant name length. The merchant’s name gets the characters left over: 15 when no text prints, or 14 minus the length of your text when it does, down to 5 for a 9-character text.

These are the lines the rules produce for two merchants:

Merchant `name`	`soft_descriptor`	Printed line
`Corner Store Burgers`	Omitted	`<facilitator>*CORNERSTOREBURG`
`Corner Store Burgers`	`ORDER-42`	`<facilitator>CORNERORDER-42`
`Corner Store Burgers`	`ORDER-2025-11`	`<facilitator>CORNEORDER-202`
`Açaí do João`	`Pedido 1234`	`<facilitator>ACAIDPEDIDO123`
`Açaí do João`	`---`	`<facilitator>*ACAIDOJOAO`

In the fourth row, Rinne removes the space from Pedido 1234 before the 9-character cut, and the cut then drops the final 4. In the last row, --- has no letter or digit, so Rinne drops it and the line ends at the merchant’s name.

To print your text as sent, keep it to 9 characters or fewer, include at least one letter or digit, and use only A-Z, 0-9 and % $ , . / & ( ) + = < > -. Longer text is accepted and cut without an error, so two references that differ only in their last characters, such as ORDER-2025-11 and ORDER-2025-12, print the same line. Each character of text also takes one from the merchant’s name, so shorter text leaves more of the name visible.

Which transactions print your text

Card transactions you create with POST /v1/transactions or POST /v1/merchants/{merchantId}/transactions print your text, whether the card arrives as a card number, a wallet network_token or a stored card_id.
A transaction that moves to AWAITING_3DS prints the same line once you call /authenticate. You send soft_descriptor only on the create request; /authenticate reuses it.

The API never returns the composed line, and sandbox transactions reach no card statement. The transaction’s soft_descriptor confirms the text Rinne received; use the rules above to predict what the cardholder sees.

Example: card transaction with a statement descriptor

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/transactions' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "CAPPTA",
    "request_id": "order-card-0005",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "installments": 1,
    "soft_descriptor": "ORDER-42",
    "card_data": {
      "number": "ev:encrypted:card_number",
      "cvv": "ev:encrypted:cvc",
      "expiry_month": "12",
      "expiry_year": "2028",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111"
    }
  }'

Example response

{
  "id": "a10ef766-8c7c-4192-8796-15058484c6bf",
  "request_id": "order-card-0005",
  "status": "APPROVED",
  "amount": 25990,
  "currency": "BRL",
  "payment_method": "CREDIT_CARD",
  "soft_descriptor": "ORDER-42"
}

For a merchant whose name is Corner Store Burgers, the cardholder’s statement shows <facilitator>*CORNER*ORDER-42.

Card transaction lifecycle highlights

Status	Meaning	Typical next action
`PROCESSING`	Authorization in progress	Wait for webhook/result fetch
`AWAITING_3DS`	Paused until your integration runs 3DS — Rinne does not contact the cardholder	Create a 3DS session, mount the 3DS element, then call `/authenticate`
`AUTHORIZED`	Authorized but not captured	Follow capture policy
`APPROVED`	Payment accepted	Fulfill order
`REFUSED`	Payment declined	Retry with new attempt/payment method

Reproduce approvals, declines, and provider errors on demand in the sandbox with deterministic test scenarios — the transaction amount selects the final payment outcome.

Retry and idempotency

Generate one request_id per attempt.
Reuse same request_id only for safe retries of the same attempt.
Use a new request_id for a new customer attempt.

Refunding card transactions

Send refund_amount equal to the remaining refundable amount for a full refund, or any smaller amount for a partial refund (subject to the rules below).

cURL

curl -X POST 'https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/refunds' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "refund_amount": 25990,
    "refund_reason": "CUSTOMER_REQUEST",
    "description": "Full refund - same day"
  }'

Card refund rules

Two independent acquirer rules apply to every card refund. Both are pre-validated server-side and surface as HTTP 400 VALIDATION_ERROR before any provider round-trip.

One successful refund per card transaction. Once a CREDIT_CARD or DEBIT_CARD transaction has a refund in COMPLETED status, the acquirer treats it as terminally refunded. Any additional refund request — partial or full — is rejected with HTTP 400.Plan the refund amount up front: if you need to return funds in pieces, the first successful refund must cover the full remaining amount you intend to return. Refunds in FAILED or CANCELLED status do not count toward this rule, so you can submit a new attempt after a failed one.

Same-day partial refunds are not allowed. When a refund request lands on the same calendar day as the transaction’s approved_at (D0), only a refund for the full remaining refundable amount is accepted. Partial refunds are allowed only from the next calendar day (D+1) onward.

The acceptance matrix on a transaction approved with approved_amount = 10000 and no prior COMPLETED refund:

Day	Refund amount	Result
D0 (same day)	10000 (full)	Accepted (outcome resolved per response semantics below)
D0 (same day)	5000 (partial)	Rejected — `400` `VALIDATION_ERROR`: `Partial refund on the same day as the transaction is not allowed by the acquirer; submit the full remaining amount or wait until D+1`
D+1 or later	5000 (partial)	Accepted (outcome resolved per response semantics below)
D+1 or later	10000 (full)	Accepted (outcome resolved per response semantics below)

Once any refund on the transaction reaches COMPLETED, every row above is rejected with HTTP 400 (Card transaction has already been refunded; the acquirer does not allow additional refunds), regardless of the day or whether the new request is partial or full.

Card refund response semantics

Card refunds resolve synchronously whenever the acquirer returns a definitive answer:

A successful cancel returns refund.status = COMPLETED and the transaction status becomes REFUNDED (full) or PARTIALLY_REFUNDED (partial).
A definitive provider rejection (for example, an acquirer business decline) returns refund.status = FAILED. Failed card refunds are terminal and are not retried — submit a new refund request to try again.
An uncertain outcome (acquirer 5xx or network timeout) triggers an inline status query against the acquirer. If that resolves the outcome, you still get COMPLETED or FAILED on the same call. Otherwise the refund moves to TIMEOUT and is reconciled asynchronously.
A PENDING_REFUND transaction status on a card transaction means the request was accepted but did not produce a definitive answer; we will retry the (idempotent) cancel.

For the full set of refund rules, statuses, and the cancel-pending-refund endpoint, see Refunds in the Transactions concept.

Integration with rinne-js

Use Card Element for encrypted card capture.
Use Guide: Card + 3DS Checkout for frontend 3DS orchestration.
Use 3D Secure authentication for backend 3DS API contracts.

Your card integration is production-ready when you correctly handle PROCESSING, AWAITING_3DS, APPROVED, REFUSED, and the CHALLENGE_NOT_ALLOWED status reason.

Getting started

Core concepts

Guides

Card transactions

Transaction endpoints (self vs merchant)

Prerequisites

Sending card data

Required transaction shape

Card data rules

3DS challenge strategy flags

Why these flags are useful

`CHALLENGE_NOT_ALLOWED` status reason

Policy granularity

Example: standard card transaction

Example: charge a stored card

Example: force transaction-first 3DS

Example: fail fast when challenge is not allowed

Card statement descriptor

How Rinne composes the statement line

Which transactions print your text

Example: card transaction with a statement descriptor

Card transaction lifecycle highlights

Retry and idempotency

Refunding card transactions

Card refund rules

Card refund response semantics

Integration with rinne-js

​Transaction endpoints (self vs merchant)

​Prerequisites

​Sending card data

​Required transaction shape

​Card data rules

​3DS challenge strategy flags

​Why these flags are useful

​CHALLENGE_NOT_ALLOWED status reason

​Policy granularity

​Example: standard card transaction

​Example: charge a stored card

​Example: force transaction-first 3DS

​Example: fail fast when challenge is not allowed

​Card statement descriptor

​How Rinne composes the statement line

​Which transactions print your text

​Example: card transaction with a statement descriptor

​Card transaction lifecycle highlights

​Retry and idempotency

​Refunding card transactions

​Card refund rules

​Card refund response semantics

​Integration with rinne-js

Transaction endpoints (self vs merchant)

Prerequisites

Sending card data

Required transaction shape

Card data rules

3DS challenge strategy flags

Why these flags are useful

`CHALLENGE_NOT_ALLOWED` status reason

Policy granularity

Example: standard card transaction

Example: charge a stored card

Example: force transaction-first 3DS

Example: fail fast when challenge is not allowed

Card statement descriptor

How Rinne composes the statement line

Which transactions print your text

Example: card transaction with a statement descriptor

Card transaction lifecycle highlights

Retry and idempotency

Refunding card transactions

Card refund rules

Card refund response semantics

Integration with rinne-js