Skip to main content
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)

ContextCreate transactionAuthenticate pending transaction
Self (company)POST /v1/transactionsPOST /v1/transactions/{id}/authenticate
Organization on behalf of merchantPOST /v1/merchants/{merchantId}/transactionsPOST /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 RinneJS secure components.
Do not collect raw PAN/CVC in custom inputs. Forward encrypted values from Card Element only.

​
Required transaction shape

​
provider
string
required
Payment provider configured for the affiliation.
​
request_id
string
required
Idempotency key for creation.
​
amount
integer
required
Amount in cents.
​
capture_method
string
required
Use ECOMMERCE for card-not-present checkout.
​
payment_method
string
required
CREDIT_CARD or DEBIT_CARD.
​
card_data
object
required
Card payload for card transactions.

​
Card data rules

  • Send exactly one of card_data.number or card_data.network_token.
  • Send expiry_month (MM) and expiry_year (YYYY).
  • 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 both number and network_token in the same request.

​
3DS challenge strategy flags

TransactionCreateRequest supports two optional card-only flags:
​
require_3ds
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.
​
refuse_on_challenge
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

FlagImmediate status behaviorWhat your backend still handlesWhat this avoids
require_3dsAlways creates card transactions in AWAITING_3DSCreate 3DS session, complete challenge when required, and call /authenticateImplementing a second session-first architecture only to enforce 3DS policy
refuse_on_challengeReturns REFUSED with status_reason=CHALLENGE_NOT_ALLOWED when challenge would be requiredHandle refusal/retry paths onlyImplementing 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": "RINNE",
    "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"
    }
  }'

​
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": "RINNE",
    "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"
    },
    "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": "RINNE",
    "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"
    },
    "refuse_on_challenge": true
  }'
Example response
{
  "id": "tx_123456789",
  "status": "REFUSED",
  "status_reason": "CHALLENGE_NOT_ALLOWED"
}

​
Card transaction lifecycle highlights

StatusMeaningTypical next action
PROCESSINGAuthorization in progressWait for webhook/result fetch
AWAITING_3DS3DS authentication requiredComplete 3DS and call /authenticate
AUTHORIZEDAuthorized but not capturedFollow capture policy
APPROVEDPayment acceptedFulfill order
REFUSEDPayment declinedRetry with new attempt/payment method

​
Retry and idempotency

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

​
Integration with RinneJS

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