Crear un cobro PayIN

PayIN permite que un merchant emita cobros mediante Orkestral. La plataforma selecciona el Proveedor de Servicios de Pago (PSP) configurado en el flujo de pago y acompaña la transacción hasta su estado final.

Antes de comenzar

Necesitas:

• una cuenta activa en Orkestral;
• al menos un PSP registrado;
• un flujo para cada medio de pago;
• un token OAuth/JWT;
• el UUID del merchant (merchantId);
• una URL HTTPS pública si deseas recibir webhooks.

Ambientes

Ambiente	URL base
QAS	https://api-qas.orkestralpay.com.br

Solicita al equipo de Orkestral la URL y las credenciales de producción. No reutilices tokens o credenciales entre ambientes.

Autenticación

Envía el token en el header Authorization:

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"
  }'

Reemplaza fechas, identificadores, URLs y credenciales con los valores de tu ambiente. La fecha de expiración debe estar en el futuro.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
transaction_id	UUID	Sí	Identificador único definido por el merchant.
amount	entero	Sí	Valor positivo en la unidad menor. Ej.: 100 = 1,00.
currency	string	Sí	Código de moneda en mayúsculas.
description	string	No	Descripción del cobro.
payment_method	string	No	Medio de pago seleccionado.
origin_url	string	No	URL de origen del checkout.
ok_url	string	No	Redirección después del éxito.
error_url	string	No	Redirección después de un error.
webhook_url	string	No	Endpoint que recibe las actualizaciones.
client	objeto	Condicional	Datos del pagador exigidos por algunos PSP.
beneficiary_sender	objeto	Condicional	Requerido por WePayments.
product_info	objeto	No	Datos del producto.
expiration	fecha/hora	Sí	Fecha futura en formato ISO 8601 local.

Los campos condicionales y la información adicional dependen del PSP y del medio de pago.

Valores aceptados

Campo	Valores
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

Los tipos de documento dependen del país y del PSP. Algunos ejemplos son CPF, CNPJ, CC, CE, DNI, NIT, RFC y RUC.

Crear sin medio de pago

Omite payment_method cuando el cliente lo elegirá posteriormente:

{
  "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"
}

La transacción puede crearse con el estado WAITING_PAYMENT_METHOD.

Respuesta exitosa

La creación exitosa devuelve 201 Created. Los campos opcionales dependen del PSP y del medio de pago:

{
  "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"
}

Guarda id para la conciliación. Un cobro creado no está necesariamente pagado; utiliza el estado de la respuesta y los webhooks.

Tratamiento de errores

HTTP	Causa común	Acción recomendada
400	Campo, moneda o medio inválido	Corrige el payload antes de repetir.
401	Token ausente, inválido o vencido	Obtén un token válido.
403	Credencial sin acceso	Revisa los permisos del merchant.
404	Merchant o configuración inexistente	Revisa merchantId y el ambiente.
409	Identificador ya utilizado	Concilia el cobro original.
422	Regla de negocio o configuración del PSP	Revisa el PSP y el flujo.
5xx	Falla temporal	Consulta la transacción antes de repetir y usa backoff.

No repitas con otro transaction_id después de un timeout o error 5xx hasta confirmar si la primera solicitud fue procesada.

Webhooks

Orkestral envía las actualizaciones al webhook_url de la transacción o a la URL predeterminada del merchant, cuando corresponda:

PATCH <webhook_url>
Content-Type: application/json
IP: <dirección del servicio notificador>

{
  "status": {
    "paymentStatusId": 3,
    "name": "APPROVED"
  },
  "message": "Pago aprobado"
}

Responde rápidamente con un estado HTTP 2xx. Las entregas fallidas se reintentan, por lo que debes procesarlas de forma idempotente. El header IP no es una firma criptográfica y no debe ser el único mecanismo de autenticación del origen.

Los estados PayIN son WAITING_CUSTOMER_PAYMENT, EXPIRED, APPROVED, DENIED, ERROR, WAITING_PAYMENT_METHOD, CHARGEBACK, WAITING_REFUND, REFUNDED, REFUND_ERROR, DECLINED y CAPTURED.

Seguridad y PCI DSS

• Nunca envíes PAN, CVV o datos de tarjeta sin tokenizar a este endpoint.
• Utiliza el flujo de tokenización/SDK aprobado por Orkestral.
• Mantén los tokens exclusivamente en servicios backend.
• No registres credenciales ni datos sensibles en logs.
• Utiliza TLS y certificados HTTPS válidos.
• La tokenización reduce la exposición, pero no elimina automáticamente las obligaciones PCI DSS del merchant.

Consulta también Clave secreta y URL de notificación.