Rinne API Documentation

This page is for organizations that have a hard requirement to handle raw card data server-side — for example, you need to forward it through your own PCI proxy to multiple partners. If you don’t have such a requirement, use the rinne-js Card Element instead — it keeps raw card data out of your systems entirely. Most integrations should use rinne-js.

Rinne’s API only accepts card credentials in encrypted form. By default, those encrypted values come from the rinne-js secure components, which encrypt the card number and CVV in the customer’s browser so raw card data never touches your servers. If your organization is PCI DSS certified to handle raw card data — for example, you operate your own vault — or you use a PCI proxy, you can instead send the raw card number and CVV through dedicated PCI base URLs. The values are encrypted in transit, before the request reaches Rinne’s API, so Rinne never receives or stores them in plain text.

PCI base URLs

Environment	PCI base URL
Sandbox	`https://pci.api-sandbox.rinne.com.br/core`
Production	`https://pci.api.rinne.com.br/core`

Requests to these base URLs work exactly like the regular API: same paths, same API keys (x-api-key), same request and response shapes. The only difference is that the number and cvv values are encrypted in transit, before the request reaches Rinne’s API. All other fields pass through unchanged.

The PCI base URLs accept raw number and cvv values only. Values already encrypted by rinne-js (ev: prefix) are not supported here and will fail. Send rinne-js-encrypted values to the regular base URLs, and raw values to the PCI base URLs — never mix them.

Example

cURL

curl -X POST 'https://pci.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-0004",
    "amount": 25990,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "CREDIT_CARD",
    "installments": 1,
    "card_data": {
      "number": "4111111111111111",
      "cvv": "123",
      "expiry_month": "12",
      "expiry_year": "2028",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111"
    }
  }'

Supported operations

The PCI base URLs serve only the operations that accept card data:

POST /v1/transactions and POST /v1/merchants/{merchantId}/transactions
POST /v1/3ds-sessions and POST /v1/merchants/{merchantId}/3ds-sessions

Every other path returns 404 on the PCI base URLs. Use the regular base URLs for everything else — refunds, queries, /authenticate, and so on; those requests never carry raw card data.

Wallet credentials (network_token and cryptogram) always come from the rinne-js wallet elements, which emit them already encrypted. The PCI endpoints apply only to raw card numbers and CVVs and will not accept wallet credentials.

Use the PCI endpoints only if your organization is PCI DSS certified to handle raw card data or uses a PCI proxy. Otherwise, use the Card Element — it keeps raw card data out of your systems entirely.

Getting started

Core concepts

Guides

PCI endpoints

PCI base URLs

Example

Supported operations

​PCI base URLs

​Example

​Supported operations

PCI base URLs

Example

Supported operations