Skip to main content
POST
/
v1
/
transactions
Create a new transaction
curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "provider": "CELCOIN",
  "request_id": "req-pix-12345",
  "amount": 10050,
  "currency": "BRL",
  "capture_method": "ECOMMERCE",
  "payment_method": "PIX",
  "pix_data": {
    "pix_key_id": "pix-key-123",
    "description": "Payment for order #12345",
    "expiration_in_seconds": 3600
  },
  "consumer": {
    "full_name": "João Silva",
    "email": "joao@email.com",
    "document_type": "CPF",
    "document_number": "81146431023",
    "phone": "+5511999999999"
  },
  "metadata": {
    "order_id": "order-12345",
    "customer_id": "cust-789"
  }
}'
{
  "id": "tx_123456789",
  "provider": "CELCOIN",
  "affiliation_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "provider_transaction_id": "prov_tx_123456",
  "request_id": "request-123",
  "mcc": "5411",
  "amount": 10050,
  "currency": "BRL",
  "pricing": {
    "fee": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    },
    "cost": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    }
  },
  "fee_policy_id": "fee_policy_123",
  "cost_policy_id": "cost_policy_123",
  "approved_amount": 10050,
  "refunded_amount": 0,
  "status": "APPROVED",
  "acquirer_response_code": "00",
  "acquirer_name": "Visa",
  "capture_method": "EMV",
  "installments": 1,
  "payment_method": "PIX",
  "pix_data": {
    "pix_key_id": "pix_key_123",
    "description": "Payment for order #123",
    "qr_code": "00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test Company6008São Paulo62070503***6304E2CA",
    "expires_at": "2023-12-02T10:00:00.000Z",
    "identification": "order_123",
    "expiration_in_seconds": 86400,
    "end_to_end_id": "E12345678202312101234567890123456"
  },
  "soft_descriptor": "MYSTORE",
  "serial_number": "12345678",
  "nsu": "000123",
  "metadata": {},
  "latest_refund_at": "2023-12-01T10:00:00.000Z",
  "provider_created_at": "2023-12-01T09:00:00.000Z",
  "status_reason": "PROVIDER",
  "approved_at": "2023-12-01T10:00:00.000Z",
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "company_full_name": "Test Company",
  "company_name": "Test Company",
  "organization_id": "tx_organization_123456",
  "consumer": {
    "full_name": "João Silva",
    "email": "joao@email.com",
    "pix_key": "joao@email.com",
    "document_type": "CPF",
    "document_number": "81146431023",
    "phone": "+5511999999999",
    "birth_date": "15-08-1990",
    "address": {
      "street": "Rua das Flores",
      "street_number": "123",
      "complement": "Apt 101",
      "neighborhood": "Centro",
      "zipcode": "12345678",
      "country": "076",
      "state": "SP",
      "city": "São Paulo"
    }
  },
  "created_at": "2023-12-01T10:00:00.000Z",
  "updated_at": "2023-12-01T10:00:00.000Z"
}

Authorizations

​
x-api-key
string
header
required

Company API key for authentication

Body

application/json

Schema for creating a new transaction.

Required fields: provider, request_id, amount, capture_method, payment_method

Conditional requirements:

  • installments must be 1 when payment_method is PIX, if not sent, defaults to 1
​
provider
enum<string>
required

Payment provider identifier

Available options:
CELCOIN
Example:

"CELCOIN"

​
request_id
string
required

Unique request ID for this transaction (used for idempotency)

Minimum length: 1
Example:

"request-123"

​
amount
integer
required

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

Required range: x >= 1
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
  • BOLETO: Bank slip payment
  • MONEY: Cash payment
  • PIX: Instant payment
Available options:
CREDIT_CARD,
DEBIT_CARD,
BOLETO,
MONEY,
PIX
Example:

"PIX"

​
currency
enum<string>
default:BRL

Transaction currency (defaults to BRL)

Available options:
BRL
Example:

"BRL"

​
installments
integer
default:1

Number of installments (1-18). Must be 1 for PIX payments.

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

1

​
pix_data
object

PIX-specific data for creating PIX transactions.

Example:
{
  "pix_key_id": "pix_key_123",
  "description": "Payment for order #123",
  "expiration_in_seconds": 3600
}
​
consumer
object

Optional consumer/customer information Optional consumer/customer information for the transaction.

Required field: document_type

Note: This information is useful for compliance and customer tracking.

Example:
{
  "full_name": "João Silva",
  "email": "joao@email.com",
  "pix_key": "joao@email.com",
  "document_type": "CPF",
  "document_number": "81146431023",
  "phone": "+5511999999999",
  "birth_date": "15-08-1990"
}
​
metadata
object

Optional additional metadata (key-value pairs)

Example:
{
  "order_id": "order-123",
  "customer_id": "cust-456"
}
​
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:
[
  {
    "company_id": "company-1",
    "amount": 5000,
    "charge_processing_cost": true
  },
  {
    "company_id": "company-2",
    "amount": 5050,
    "charge_processing_cost": false
  }
]
​
soft_descriptor
string

Optional text shown on cardholder statement (max 13 chars)

Maximum length: 13
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:

"507f1f77bcf86cd799439011"

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
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,
REFUSED,
EXPIRED
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,
BOLETO,
MONEY,
PIX
Example:

"PIX"

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

​
provider_transaction_id
string | null

Transaction ID in provider system

Example:

"prov_tx_123456"

​
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

​
acquirer_response_code
string | null

Acquirer response code

Example:

"00"

​
acquirer_name
string | null

Acquirer name

Example:

"Visa"

​
pix_data
object

PIX-specific data (present if payment_method is PIX)

​
soft_descriptor
string | null

Soft descriptor shown on cardholder statement

Example:

"MYSTORE"

​
serial_number
string | null

Terminal serial number

Example:

"12345678"

​
nsu
string | null

Network Sequential Number

Example:

"000123"

​
metadata
object

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"

​
provider_created_at
string<date-time> | null

Creation timestamp in provider system

Example:

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

​
status_reason
enum<string> | null

Status reason details

Available options:
PROVIDER,
ACQUIRER,
ANTIFRAUD,
INTERNAL_ERROR,
NO_ACQUIRER,
ACQUIRER_TIMEOUT
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

Consumer information

​
updated_at
string<date-time> | null

Transaction last update timestamp

Example:

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