Saltar al contenido principal

Confirmar un Payment Intent

Confirma un Payment Intent para obtener la URL a la que redirigir a tu cliente para que complete el pago.

Endpoint​

POST /api/v1/payment_intents/:id/confirm

Autenticación​

Este endpoint admite ambos métodos de autenticación:

  • Token Bearer (JWT): Authorization: Bearer YOUR_JWT_TOKEN
  • Clave de API (Basic Auth): Authorization: Basic base64(key:secret)

Petición​

Parámetros de ruta​

ParámetroTipoObligatorioDescripción
idstringSíEl ID del Payment Intent que se confirma (por ejemplo 550e8400-e29b-41d4-a716-446655440000).

Cuerpo de la petición​

{
  "client_secret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "return_url": "https://merchant.example.com/return",
  "payment_method_data": {
    "type": "crypto"
  }
}

Parámetros​

ParámetroTipoObligatorioDescripción
client_secretstringSíEl client secret de la respuesta de creación del Payment Intent.
return_urlstringNoSustituye la URL de retorno indicada al crear el Payment Intent.
payment_method_dataobjectNoDatos del método de pago. Actualmente solo se admite type: "crypto".

Respuesta​

Respuesta correcta​

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "requires_confirmation",
  "paymentMethodTypes": ["crypto"],
  "clientSecret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "returnUrl": "https://merchant.example.com/return",
  "nextAction": {
    "type": "redirect_to_url",
    "redirectToUrl": {
      "url": "https://pay.orcarail.com/pay/pl_abc123?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123"
    }
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Campos de la respuesta​

CampoTipoDescripción
idstringEl ID del Payment Intent.
statusstringEstado actualizado (normalmente requires_confirmation).
nextActionobjectContiene la URL de redirección en redirectToUrl.url.
nextAction.typestringSiempre "redirect_to_url" en los pagos cripto.
nextAction.redirectToUrl.urlstringLa URL a la que debes redirigir a tu cliente. Es la página de pago alojada.

Ejemplo​

cURL​

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000/confirm \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123"
  }'

JavaScript (Node.js)​

const paymentIntentId = '550e8400-e29b-41d4-a716-446655440000'
const clientSecret = '550e8400-e29b-41d4-a716-446655440000_secret_abc123'

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}/confirm`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      client_secret: clientSecret,
    }),
  }
)

const confirmedIntent = await response.json()
const redirectUrl = confirmedIntent.nextAction.redirectToUrl.url

// Redirect your customer to this URL
window.location.href = redirectUrl

Python​

import requests

payment_intent_id = '550e8400-e29b-41d4-a716-446655440000'
client_secret = '550e8400-e29b-41d4-a716-446655440000_secret_abc123'

response = requests.post(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}/confirm',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'client_secret': client_secret,
    },
)

confirmed_intent = response.json()
redirect_url = confirmed_intent['nextAction']['redirectToUrl']['url']

# Redirect your customer to this URL
print(f"Redirect customer to: {redirect_url}")

PHP (SDK)​

$confirmed = $orcarail->paymentIntents->confirm($intentId, [
    'client_secret' => $clientSecret,
    'return_url' => 'https://merchant.example.com/return',
]);

$payUrl = $confirmed->pay_url ?? $confirmed->next_action?->redirect_to_url?->url;
header('Location: ' . $payUrl);

El SDK de PHP envía tu clave de API junto con el client secret, así que la confirmación funciona desde un servidor sin JWT de usuario.

Flujo de pago alojado​

Tras confirmar el Payment Intent, redirige a tu cliente a la URL de nextAction.redirectToUrl.url. Esta página de pago alojada:

  1. Muestra el importe y los detalles del pago
  2. Permite al cliente conectar su wallet cripto
  3. Procesa el pago on-chain
  4. Redirige de vuelta a tu return_url con parámetros de consulta

Gestión de la URL de retorno​

Tras completar (o cancelar) el pago, los clientes vuelven a tu return_url con parámetros de consulta:

https://merchant.example.com/return?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123

Deberías:

  1. Extraer payment_intent y payment_intent_client_secret de la cadena de consulta
  2. Obtener el Payment Intent para comprobar su estado
  3. Gestionar el pago en consecuencia (por ejemplo, mostrar una página de éxito o actualizar el estado del pedido)

Ejemplo de gestor de la URL de retorno​

// Handle return URL callback
const urlParams = new URLSearchParams(window.location.search)
const paymentIntentId = urlParams.get('payment_intent')
const clientSecret = urlParams.get('payment_intent_client_secret')

if (paymentIntentId && clientSecret) {
  // Retrieve the Payment Intent to check status
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const paymentIntent = await response.json()

  if (paymentIntent.status === 'succeeded') {
    // Payment successful!
    showSuccessPage()
  } else if (paymentIntent.status === 'canceled') {
    // Payment was canceled
    showCanceledPage()
  } else {
    // Payment is still processing
    showProcessingPage()
  }
}

Próximos pasos​