Recarga.do API

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Balance insuficiente para procesar la operación.",
    "details": { "saldo_disponible": 120.00, "monto_requerido": 500.00 }
  },
  "request_id": "req_9f2c1ab34de5f6a7b8c9d0e1"
}

<?php

class RecargaDo
{
    public function __construct(
        private string $apiKey,
        private string $apiSecret,
        private string $base = 'https://api.recarga.do'
    ) {}

    public function recargar(int $servicioId, string $numero, float $monto, string $idemKey): array
    {
        $ch = curl_init($this->base . '/v1/recharges');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST           => true,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . $this->apiKey . '.' . $this->apiSecret,
                'Idempotency-Key: ' . $idemKey,
                'Content-Type: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode([
                'service_id' => $servicioId,
                'identifier' => $numero,
                'amount'     => $monto,
            ]),
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT        => 40,
        ]);

        $body   = curl_exec($ch);
        $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return ['status' => $status, 'body' => json_decode((string) $body, true) ?? []];
    }
}

// La clave se genera UNA vez y se persiste con la orden.
$orden->idem_key ??= sprintf('%s-%s', $orden->id, bin2hex(random_bytes(16)));
$orden->save();

$api = new RecargaDo(getenv('RECARGA_KEY'), getenv('RECARGA_SECRET'));
$r   = $api->recargar(23, '8095551235', 100.00, $orden->idem_key);

switch ($r['status']) {
    case 201:
        $orden->marcarCobrada($r['body']['data']['transaction_id']);
        break;

    case 202: // Desconocido: el importe está retenido, NO reintentar
        $orden->marcarVerificando($r['body']['error']['details']['transaction_id']);
        break;

    case 409: // La original sigue en curso: reintentar con LA MISMA clave
        $orden->programarReintento();
        break;

    case 502: // Rechazo definitivo: el saldo ya fue devuelto
        $orden->marcarFallida($r['body']['error']['code']);
        break;

    default:  // Ante la duda, verificar antes de decidir
        $orden->marcarVerificando(null);
}

import { randomUUID } from 'node:crypto';

const BASE = 'https://api.recarga.do';
const AUTH = `Bearer ${process.env.RECARGA_KEY}.${process.env.RECARGA_SECRET}`;

async function recargar({ serviceId, identifier, amount, idemKey }) {
  const res = await fetch(`${BASE}/v1/recharges`, {
    method: 'POST',
    headers: {
      'Authorization': AUTH,
      'Idempotency-Key': idemKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ service_id: serviceId, identifier, amount }),
    signal: AbortSignal.timeout(40_000),
  });
  return { status: res.status, body: await res.json() };
}

// La clave se genera UNA vez y se guarda con la orden.
orden.idemKey ??= randomUUID();
await orden.save();

let r;
try {
  r = await recargar({ serviceId: 23, identifier: '8095551235', amount: 100, idemKey: orden.idemKey });
} catch (e) {
  // Timeout de red: la recarga PUDO ejecutarse. Reintentar con LA MISMA clave.
  r = await recargar({ serviceId: 23, identifier: '8095551235', amount: 100, idemKey: orden.idemKey });
}

switch (r.status) {
  case 201:
    await orden.cobrada(r.body.data.transaction_id);
    break;
  case 202: // Retenido, no cobrado. Consultar; nunca reintentar con clave nueva.
    await orden.verificando(r.body.error.details.transaction_id);
    break;
  case 409: // Sigue en curso
    await orden.reintentarEn(2000);
    break;
  case 502: // Saldo ya devuelto
    await orden.fallida(r.body.error.code);
    break;
  default:
    await orden.verificando(null);
}

import os, uuid, requests

BASE = "https://api.recarga.do"
AUTH = f"Bearer {os.environ['RECARGA_KEY']}.{os.environ['RECARGA_SECRET']}"


def recargar(service_id: int, identifier: str, amount: float, idem_key: str):
    r = requests.post(
        f"{BASE}/v1/recharges",
        headers={
            "Authorization": AUTH,
            "Idempotency-Key": idem_key,
            "Content-Type": "application/json",
        },
        json={"service_id": service_id, "identifier": identifier, "amount": amount},
        timeout=(5, 40),
    )
    return r.status_code, r.json()


# La clave se genera UNA vez y se persiste con la orden.
if not orden.idem_key:
    orden.idem_key = str(uuid.uuid4())
    orden.save()

try:
    status, body = recargar(23, "8095551235", 100.00, orden.idem_key)
except requests.Timeout:
    # La recarga PUDO ejecutarse: se reintenta con LA MISMA clave.
    status, body = recargar(23, "8095551235", 100.00, orden.idem_key)

if status == 201:
    orden.cobrada(body["data"]["transaction_id"])
elif status == 202:
    # Importe retenido, no cobrado. Consultar, nunca reintentar con clave nueva.
    orden.verificando(body["error"]["details"]["transaction_id"])
elif status == 409:
    orden.reintentar_en(segundos=2)
elif status == 502:
    # Rechazo definitivo: el saldo ya fue devuelto.
    orden.fallida(body["error"]["code"])
else:
    orden.verificando(None)