Skip to main content
POST
/
v1
/
merchants
/
{merchantId}
/
transactions
curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/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": "[email protected]",
    "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",
  "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
    }
  },
  "status": "APPROVED",
  "capture_method": "EMV",
  "installments": 1,
  "payment_method": "PIX",
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "created_at": "2023-12-01T10:00:00.000Z",
  "provider_transaction_id": "prov_tx_123456",
  "fee_policy_id": "fee_policy_123",
  "cost_policy_id": "cost_policy_123",
  "approved_amount": 10050,
  "refunded_amount": 0,
  "acquirer_response_code": "00",
  "acquirer_name": "Visa",
  "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",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "interest": {
      "modality": "PERCENTAGE_PER_MONTH",
      "amount": 1000,
      "percentage": 10.5
    },
    "fine": {
      "modality": "PERCENTAGE",
      "amount": 2000,
      "percentage": 2.5
    },
    "discount": {
      "modality": "PERCENTAGE_UNTIL_DATE",
      "amount": 2,
      "percentage": 50,
      "discount_dates_config": [
        {
          "until_date": "2025-12-15",
          "percentage": 10
        },
        {
          "until_date": "2025-12-20",
          "percentage": 5
        }
      ]
    },
    "abatement": {
      "modality": "FIXED",
      "amount": 5000,
      "percentage": 5
    }
  },
  "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_full_name": "Test Company",
  "company_name": "Test Company",
  "organization_id": "tx_organization_123456",
  "consumer": {
    "document_type": "CPF",
    "full_name": "João Silva",
    "email": "[email protected]",
    "pix_key": "[email protected]",
    "document_number": "81146431023",
    "phone": "+5511999999999",
    "birth_date": "15-08-1990",
    "address": {
      "street": "Rua das Flores",
      "neighborhood": "Centro",
      "zipcode": "12345678",
      "country": "076",
      "state": "SP",
      "city": "São Paulo",
      "street_number": "123",
      "complement": "Apt 101"
    }
  },
  "updated_at": "2023-12-01T10:00:00.000Z"
}

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.

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
  • When pix_data.due_date is provided: consumer is required with full_name, document_number, and document_type
  • When pix_data.due_date is provided: expiration_in_seconds must not be provided. Use expiration_in_days_after_due_date instead
  • When pix_data.due_date is NOT provided: expiration_in_days_after_due_date must not be provided. Use expiration_in_seconds instead
​
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 string 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.

  • Interest, fine, discount, and abatement can only be applied when due_date is provided.
  • When due_date is provided: expiration_in_seconds must not be provided. Use expiration_in_days_after_due_date instead
  • When due_date is NOT provided: expiration_in_days_after_due_date must not be provided. Use expiration_in_seconds instead
  • When using discount with FIXED_AMOUNT_UNTIL_DATE or PERCENTAGE_UNTIL_DATE modality: all discount_dates_config dates must be before or equal to due_date
Example:
{
  "pix_key_id": "pix_key_123",
  "description": "Payment for order #123",
  "expiration_in_seconds": 3600,
  "due_date": "2025-12-31",
  "expiration_in_days_after_due_date": 30,
  "interest": {
    "percentage": 1,
    "modality": "PERCENTAGE_PER_MONTH"
  },
  "fine": { "percentage": 2, "modality": "PERCENTAGE" },
  "discount": {
    "modality": "PERCENTAGE_UNTIL_DATE",
    "discount_dates_config": [
      {
        "until_date": "2025-12-15",
        "percentage": 10
      },
      {
        "until_date": "2025-12-20",
        "percentage": 5
      }
    ]
  }
}
​
consumer
object

Optional consumer/customer information. Required with full_name, document_number, and document_type when pix_data.due_date is provided.

Example:
{
  "full_name": "João Silva",
  "email": "[email protected]",
  "pix_key": "[email protected]",
  "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 string 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"