Primeros Pasos

Integre su aplicacion con la API de Owem Pay y realice su primera operacion PIX en pocos minutos.

1. Obtenga sus credenciales

Solicite al administrador de su cuenta Owem Pay:

• Client ID -- identificador de su API Key (prefijo cli_)
• Client Secret -- clave secreta para autenticacion y firma HMAC (prefijo sk_)

Seguridad

Nunca exponga el client_secret en codigo frontend o repositorios publicos. Utilice variables de entorno en su servidor.

2. Configure la autenticacion

Todas las solicitudes exigen el header Authorization con sus credenciales API Key:

# Formato del header:
Authorization: ApiKey {client_id}:{client_secret}

La API Key es permanente -- no expira. No es necesario generar tokens.

3. Consulte el saldo

Pruebe la integracion consultando el saldo de la cuenta:

curl -X GET https://api.owem.com.br/api/external/balance \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Respuesta:

{
  "worked": true,
  "balance": 300000,
  "available": 300000,
  "pending": 0,
  "currency": "BRL"
}

Valores monetarios

Los valores de entrada (request) son en centavos: R$ 30,00 = 3000. Los valores de respuesta son en unidades base: 300000 / 10.000 = R$ 30,00. Nunca use punto flotante -- siempre enteros.

4. Genere un cobro PIX (Cash-In)

Cree un QR Code para recibir R$ 30,00:

BODY='{"amount":3000,"description":"Pedido #1234","external_id":"order-9876"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/pix/cash-in \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Respuesta:

{
  "worked": true,
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_image": "data:image/png;base64,...",
  "external_id": "order-9876",
  "amount": 300000,
  "status": "active"
}

Note que envio 3000 (centavos) y recibio 300000 (unidades base). Ambos representan R$ 30,00.

Muestre el qr_code_image o el codigo copia y pega (qr_code) al pagador.

5. Consulte el estado

Acompane el pago consultando por el transaction_id:

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Cuando el pago sea confirmado, el status cambia a completed.

Tambien puede consultar por el external_id:

curl -X GET https://api.owem.com.br/api/external/transactions/ref/order-9876 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

6. Reciba notificaciones (Webhooks)

Para recibir notificaciones en tiempo real (recomendado en vez de polling):

BODY='{"url":"https://seusite.com.br/webhook","events":["pix.received","pix.completed"]}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/webhooks \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Proximos Pasos

• Autenticacion -- API Key + HMAC (3 capas de seguridad)
• HMAC-SHA512 -- como firmar solicitudes transaccionales
• PIX Cash-In -- generar cobros
• PIX Cash-Out -- enviar PIX por clave
• Extracto -- consultar transacciones
• Webhooks -- notificaciones en tiempo real
• Conceptos -- valores, estados, external_id, idempotencia y claves PIX