Confirm a Payment Intent

Confirm a Payment Intent to get the redirect URL for your customer to complete the payment.

Endpoint

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

Authentication

This endpoint supports both authentication methods:

• Bearer Token (JWT) - Authorization: Bearer YOUR_JWT_TOKEN
• API Key (Basic Auth) - Authorization: Basic base64(key:secret)

Request

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the Payment Intent to confirm (e.g., 550e8400-e29b-41d4-a716-446655440000).

Request Body

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

Parameters

Parameter	Type	Required	Description
client_secret	string	Yes	The client secret from the Payment Intent creation response.
return_url	string	No	Override the return URL specified when creating the Payment Intent.
payment_method_data	object	No	Payment method data. Currently only type: "crypto" is supported.

Response

Success Response

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

Response Fields

Field	Type	Description
id	string	The Payment Intent ID.
status	string	Updated status (typically requires_confirmation).
nextAction	object	Contains the redirect URL in redirectToUrl.url.
nextAction.type	string	Always "redirect_to_url" for crypto payments.
nextAction.redirectToUrl.url	string	The URL to redirect your customer to. This is the hosted pay page.

Example

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

Hosted Pay Flow

After confirming the Payment Intent, redirect your customer to the URL in nextAction.redirectToUrl.url. This hosted pay page will:

1. Display the payment amount and details
2. Allow the customer to connect their crypto wallet
3. Process the payment on-chain
4. Redirect back to your return_url with query parameters

Return URL Handling

After payment completion (or cancellation), customers are redirected to your return_url with query parameters:

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

You should:

1. Extract the payment_intent and payment_intent_client_secret from the query string
2. Retrieve the Payment Intent to check its status
3. Handle the payment accordingly (e.g., show success page, update order status)

Example Return URL Handler

// 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()
  }
}

Next Steps

• Retrieve a Payment Intent - Check payment status
• Set up Webhooks - Receive real-time payment notifications