Create a PayIN charge

PayIN allows a merchant to issue charges through Orkestral. The platform selects the Payment Service Provider (PSP) configured in the payment flow and tracks the transaction until its final state.

Before you start

You need:

• an active Orkestral account;
• at least one registered PSP;
• a payment flow for each payment method;
• an OAuth/JWT access token;
• the merchant UUID (merchantId);
• a public HTTPS URL if you want to receive webhooks.

Environments

Environment	Base URL
QAS	https://api-qas.orkestralpay.com.br

Ask the Orkestral team for the production URL and credentials. Do not reuse tokens or credentials across environments.

Authentication

Send the token in the Authorization header:

Authorization: Bearer <access_token>
Content-Type: application/json

Endpoint

POST /transaction/payin/{merchantId}

curl --request POST \
  --url "https://api-qas.orkestralpay.com.br/transaction/payin/<merchantId>" \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
    "amount": 10000,
    "currency": "COP",
    "description": "Payment for services",
    "payment_method": "TRANSFER",
    "origin_url": "https://merchant.example.com/checkout",
    "ok_url": "https://merchant.example.com/payment/success",
    "error_url": "https://merchant.example.com/payment/error",
    "webhook_url": "https://merchant.example.com/webhooks/orkestral",
    "expiration": "2027-12-31T23:59:59"
  }'

Replace dates, identifiers, URLs, and credentials with values from your environment. The expiration date must be in the future.

Request fields

Field	Type	Required	Description
transaction_id	UUID	Yes	Unique identifier assigned by the merchant.
amount	integer	Yes	Positive value in the currency's minor unit. Example: 100 = 1.00.
currency	string	Yes	Uppercase currency code.
description	string	No	Charge description.
payment_method	string	No	Selected payment method.
origin_url	string	No	Checkout origin URL.
ok_url	string	No	Redirect URL after success.
error_url	string	No	Redirect URL after an error.
webhook_url	string	No	Endpoint that receives status updates.
client	object	Conditional	Payer data required by specific PSPs.
beneficiary_sender	object	Conditional	Required by WePayments.
product_info	object	No	Product data.
expiration	date/time	Yes	Future local ISO 8601 date and time.

Conditional fields and additional information vary by PSP and payment method.

Accepted values

Field	Values
currency	BRL, COP, CRC, ECS, GTQ, PEN, MXN, NIO, PAB, HNL, CLP, SVC, USD
payment_method	CREDIT_CARD, DEBIT_CARD, WALLETS, CASH, TRANSFER, PIX, PSE

Document types depend on the country and PSP. Examples include CPF, CNPJ, CC, CE, DNI, NIT, RFC, and RUC.

Create without a payment method

Omit payment_method when the customer will select it later:

{
  "transaction_id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 10000,
  "currency": "COP",
  "description": "Payment for services",
  "webhook_url": "https://merchant.example.com/webhooks/orkestral",
  "expiration": "2027-12-31T23:59:59"
}

The transaction may be created as WAITING_PAYMENT_METHOD.

Success response

A successful request returns 201 Created. Optional fields vary by PSP and payment method:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "merchant_id": "11111111-1111-1111-1111-111111111111",
  "amount": 10000,
  "currency": "COP",
  "payment_method": "TRANSFER",
  "status": "WAITING_CUSTOMER_PAYMENT",
  "custom_code": "merchant-reference",
  "created_date": "2026-07-30T15:00:00",
  "country": "CO",
  "checkout_url": "https://checkout.example.com/transaction"
}

Store id for reconciliation. A created charge is not necessarily paid; use the response status and webhooks.

Error handling

HTTP	Common cause	Recommended action
400	Invalid field, currency, or payment method	Fix the payload before retrying.
401	Missing, invalid, or expired token	Obtain a valid token.
403	Credential cannot access the resource	Check merchant permissions.
404	Merchant or configuration not found	Check merchantId and environment.
409	Identifier already used	Reconcile the original charge.
422	Business rule or PSP configuration error	Review the PSP and payment flow.
5xx	Temporary failure	Query the transaction before retrying and use backoff.

Do not retry with a different transaction_id after a timeout or 5xx until you confirm whether the first request was processed.

Webhooks

Orkestral sends updates to the transaction's webhook_url, or to the merchant's default notification URL when applicable:

PATCH <webhook_url>
Content-Type: application/json
IP: <notifier service address>

{
  "status": {
    "paymentStatusId": 3,
    "name": "APPROVED"
  },
  "message": "Payment approved"
}

Return an HTTP 2xx response promptly. Failed deliveries are retried, so process notifications idempotently. The IP header is not a cryptographic signature and must not be the sole source-authentication mechanism.

PayIN statuses are WAITING_CUSTOMER_PAYMENT, EXPIRED, APPROVED, DENIED, ERROR, WAITING_PAYMENT_METHOD, CHARGEBACK, WAITING_REFUND, REFUNDED, REFUND_ERROR, DECLINED, and CAPTURED.

Security and PCI DSS

• Never send PAN, CVV, or raw card data to this endpoint.
• Use the Orkestral-approved tokenization/SDK flow for cards.
• Keep tokens in backend services only.
• Do not log credentials or sensitive data.
• Use TLS and valid HTTPS certificates.
• Tokenization reduces exposure but does not automatically remove the merchant's PCI DSS obligations.

See also Secret Key and Notification URL.