Payment Intents

Payment Intents let you accept card and Apple Pay payments into an account. Create an intent for the amount you want to collect, then confirm it with an intent action.

The Payment Intent object

string

Unique payment intent identifier.

string

ISO 4217 currency code. e.g. USD, GBP, EUR.

number

Amount in the smallest currency unit. 5000 = $50.00 USD.

string

Your unique order or transaction reference.

string

Optional human-readable payment description.

string

Intent status. One of requires_action, processing, completed, cancelled, or failed.

string

Reason for the current status. Present when a payment fails or is cancelled with a reason.

string

Entity that owns the payment intent.

string

Account credited when the payment completes.

number

Unix timestamp in milliseconds when the intent was created.

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc123",
  "description": "Order #1042",
  "status": "requires_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000
}

Payment intent statuses

Status	Description
`requires_action`	Intent created and ready to be confirmed.
`processing`	A confirmation action is being processed.
`completed`	Payment completed successfully.
`cancelled`	Intent was cancelled before completion.
`failed`	Payment failed. Check `status_reason`.

The Intent Action object

string

Unique intent action identifier.

string

Currency inherited from the payment intent.

number

Payment amount inherited from the payment intent.

number

Fee charged for the payment in the smallest currency unit.

number

Amount charged for the payment.

number

Amount refunded so far in the smallest currency unit.

string

Client reference inherited from the payment intent.

string

Action performed. Currently confirm.

string

Payment category. Currently collections.

string

Payment method. One of card-acq or applepay-acq.

object

Payment method data returned for the action. Sensitive card details are never returned.

string

Action status. One of pending, pending_user_action, completed, or failed.

string

Reason for the current status. Present when a payment fails.

string

Entity that owns the intent action.

string

Account credited when the payment completes.

string

Payment Intent linked to this action.

boolean

true when the customer must complete a redirect or challenge.

object

Next step for the customer when requires_action is true.

string

URL the customer is redirected to after authentication.

number

Unix timestamp in milliseconds when the action was created.

{
  "id": "01HACT9012EFGH",
  "currency": "USD",
  "amount": 5000,
  "applicable_fee": 75,
  "charge_amount": 5000,
  "refunded_amount": 0,
  "reference": "order_abc123",
  "action": "confirm",
  "category": "collections",
  "payment_type": "card-acq",
  "payment_type_data": {
    "auth_model": "3ds_required",
    "payment_country": "US",
    "last_four_digits": "1111",
    "card_brand": "visa",
    "card_type": "credit"
  },
  "status": "pending_user_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "return_url": "https://yourplatform.com/checkout/complete",
  "requires_action": true,
  "next_action": {
    "type": "redirect_to_url",
    "url": "https://checkout.nuvion.co/card/01HACT9012EFGH"
  },
  "created": 1735725600000
}

Intent action statuses

Status	Description
`pending`	Action created and being processed.
`pending_user_action`	Customer must complete authentication.
`completed`	Payment completed successfully.
`failed`	Payment failed. Check `status_reason`.

Retrieve intent_action

To rerieve an intent_action, send a GET request to this endpoint /payment-intents/:id

curl -X GET https://api.nuvion.dev/payment-intents/01HXYZ7K3M9PQRST4UVWXY2Z6 \
  -H "Authorization: Bearer $NUVION_API_KEY"\
  -H "Content-Type: application/json"\

{
    "status": "success",
    "message": "Payment intent fetched successfully",
    "data": {
        "id": "01KVFTXH5G40ER6VJPVBTZXXXX",
        "currency": "USD",
        "amount": 5000,
        "reference": "REF-1781869121102-4040",
        "description": "Test Card",
        "status": "failed",
        "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
        "account_id": "01K8TN588BZKJHZ3VHR2BFXXXX",
        "created": 1781869233328,
        "intent_action": {
            "id": "01KVFTYXYVJ327XCAXJNYAXXXX",
            "currency": "USD",
            "amount": 5000,
            "applicable_fee": 180,
            "charge_amount": 5000,
            "refunded_amount": 0,
            "reference": "REF-1781869121102-4040",
            "action": "confirm",
            "category": "collections",
            "payment_type": "card-acq",
            "payment_type_data": {
                "payment_country": "US",
                "auth_model": "3ds_required",
                "last_four_digits": "7223"
            },
            "status": "failed",
            "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
            "account_id": "01K8TN588BZKJHZ3VHR2BFXXXX",
            "payment_intent_id": "01KVFTXH5G40ER6VJPVBTZXXXX",
            "return_url": "https://www.google.com",
            "created": 1781869279195
        }
    }
}

Card data encryption

For card-acq, send encrypted card details in intent_action.payment_type_data.data. Encrypt this JSON object with RSA-OAEP SHA-256 using the encryption_public_key returned when you create or rotate an API key:

{
  "card_number": "4111111111111111",
  "expiration_month": "12",
  "expiration_year": "2030",
  "cvv": "123",
  "card_holder_name": "Ada Lovelace"
}

string

required

Card PAN. 13–19 digits. Spaces are ignored after decryption.

string

required

Expiry month, 1–12 or zero-padded 01–12.

string

required

Four-digit expiry year. The expiry date must not be in the past.

string

required

Card verification value. 3 or 4 digits.

string

Optional name printed on the card.

Never send raw card details in an API request. Only send the encrypted Base64 value in payment_type_data.data.

Create a payment intent

POST /payment-intents Creates a payment intent for a card payment.

Request parameters

string

required

ISO 4217 currency code. e.g. USD.

number

required

Amount in the smallest currency unit. 5000 = $50.00 USD.

string

required

Account to credit when the payment completes.

string

required

Unique order or transaction reference. 1–100 characters. The same reference cannot be reused for the same account.

string

A human-readable payment description. Maximum 250 characters.

object

Optional confirmation action. Include this to create and confirm the Payment Intent in one request.

Request

curl -X POST https://api.nuvion.dev/payment-intents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 5000,
    "account_id": "acc_01HXYZ5678EFGH",
    "reference": "order_abc123",
    "description": "Order #1042"
  }'

Response

Returns a Payment Intent with status: "requires_action".

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc123",
  "description": "Order #1042",
  "status": "requires_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000
}

Create and confirm in one request

Include intent_action when your server already has the encrypted card payload and wants to submit the payment immediately.

curl -X POST https://api.nuvion.dev/payment-intents \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": 5000,
    "account_id": "acc_01HXYZ5678EFGH",
    "reference": "order_abc124",
    "description": "Order #1043",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "billing_address": {
          "address_line_one": "350 Fifth Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      }
    }
  }'

{
  "id": "01HXYZ7K3M9PQRST4UVWXY2Z7",
  "currency": "USD",
  "amount": 5000,
  "reference": "order_abc124",
  "description": "Order #1043",
  "status": "completed",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "created": 1735725600000,
  "intent_action": {
    "id": "01HACT9012EFGI",
    "currency": "USD",
    "amount": 5000,
    "applicable_fee": 75,
    "charge_amount": 5000,
    "refunded_amount": 0,
    "reference": "order_abc124",
    "action": "confirm",
    "category": "collections",
    "payment_type": "card-acq",
    "payment_type_data": {
      "payment_country": "US",
      "last_four_digits": "1111",
      "card_brand": "visa",
      "card_type": "credit"
    },
    "status": "completed",
    "entity_id": "ent_01HXYZ1234ABCD",
    "account_id": "acc_01HXYZ5678EFGH",
    "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z7",
    "created": 1735725600000
  }
}

Confirm a payment intent

POST /intent-actions Confirms a payment intent with card or Apple Pay payment data.

Request parameters

string

required

Payment Intent to confirm. The intent must have status: "requires_action".

object

required

Confirmation action details.

string

required

Always confirm.

string

required

Always collections.

string

required

Payment method. One of card-acq or applepay-acq.

object

required

Payment method data.

string

Encrypted Base64 card data. Required for card-acq; omit for applepay-acq.

object

required

Billing address. For applepay-acq, only country is required.

Show billing_address fields

string

required

First line of the billing address. Required for card-acq.

string

required

Billing city. Required for card-acq.

string

required

Billing state, region, or province. Required for card-acq.

string

required

Two-letter country code. e.g. US.

string

Apartment, suite, or second address line.

string

Postal or ZIP code.

string

Card authentication model. Defaults to 3ds_required.

object

Browser data for 3DS authentication.

object

required

Customer details for the payment.

Show customer fields

string

required

Customer first name.

string

required

Customer last name.

string

required

Customer email address.

string

Customer phone number in E.164 format, when available.

string

URL to redirect the customer to after authentication. Required unless auth_model is 3ds_disabled.

Card request

curl -X POST https://api.nuvion.dev/intent-actions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "data": "<base64_encrypted_card_data>",
        "billing_address": {
          "address_line_one": "350 Fifth Avenue",
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
        "browser_info": {
          "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
          "ip_address":"213.93.4.172",
          "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
          "java_enabled": false,
          "javascript_enabled": true,
          "language": "en-US",
          "color_depth": "24",
          "screen_height": "900",
          "screen_width": "1440",
          "timezone_offset": "-300"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

Apple Pay request

curl -X POST https://api.nuvion.dev/intent-actions \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
    "intent_action": {
      "action": "confirm",
      "category": "collections",
      "payment_type": "applepay-acq",
      "payment_type_data": {
        "billing_address": {
          "country": "US"
        }
      },
      "customer": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "return_url": "https://yourplatform.com/checkout/complete"
    }
  }'

Response

Returns an Intent Action. If requires_action is true, redirect the customer to next_action.url.

{
  "id": "01HACT9012EFGH",
  "currency": "USD",
  "amount": 5000,
  "applicable_fee": 75,
  "charge_amount": 5000,
  "refunded_amount": 0,
  "reference": "order_abc123",
  "action": "confirm",
  "category": "collections",
  "payment_type": "card-acq",
  "payment_type_data": {
    "auth_model": "3ds_required",
    "payment_country": "US",
    "last_four_digits": "1111",
    "card_brand": "visa",
    "card_type": "credit"
  },
  "status": "pending_user_action",
  "entity_id": "ent_01HXYZ1234ABCD",
  "account_id": "acc_01HXYZ5678EFGH",
  "payment_intent_id": "01HXYZ7K3M9PQRST4UVWXY2Z6",
  "return_url": "https://yourplatform.com/checkout/complete",
  "requires_action": true,
  "next_action": {
    "type": "redirect_to_url",
    "url": "https://checkout.nuvion.co/card/01HACT9012EFGH"
  },
  "created": 1735725600000
}

Payment intent webhooks

Payment Intent webhooks notify your server when a payment reaches a final state.

Event	Trigger
`payment_intent.completed`	Payment completed successfully
`payment_intent.failed`	Payment failed
`payment_intent.cancelled`	Payment Intent cancelled before confirmation

{
  "event": "payment_intent.completed",
  "data": {
    "id": "01KVFTT3CBC3SGR8R8NM5WXXXX",
    "currency": "USD",
    "amount": 500000,
    "reference": "REF-1781868342495-2421",
    "description": "Test Card",
    "status": "completed",
    "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
    "account_id": "01K8TN588BZKJHZ3VHR2BFXXXX",
    "created": 1781869120907,
    "intent_action": {
      "id": "01KVFTW24AEHZ8ABX9G4ARXXXX",
      "currency": "USD",
      "amount": 500000,
      "applicable_fee": 22530,
      "charge_amount": 500000,
      "refunded_amount": 0,
      "reference": "REF-1781868342495-2421",
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "payment_country": "CA",
        "auth_model": "3ds_required",
        "last_four_digits": "1111",
        "card_brand": "visa",
        "card_type": "debit"
      },
      "status": "completed",
      "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
      "account_id": "01K8TN588BZKJHZ3VHR2BFXXXX",
      "payment_intent_id": "01KVFTT3CBC3SGR8R8NM5WXXXX",
      "return_url": "https://www.google.com",
      "created": 1781869185162
    }
  }
}

{
  "event": "payment_intent.failed",
  "data": {
    "id": "01KVFTXH5G40ER6VJPVBTZXXXX",
    "currency": "USD",
    "amount": 5000,
    "reference": "REF-1781869121102-4040",
    "description": "Test Card",
    "status": "failed",
    "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
    "account_id": "01K8TN588BZKJHZ3VHR2BXXXX",
    "created": 1781869233328,
    "intent_action": {
      "id": "01KVFTYXYVJ327XCAXJNYAXXXX",
      "currency": "USD",
      "amount": 5000,
      "applicable_fee": 180,
      "charge_amount": 5000,
      "refunded_amount": 0,
      "reference": "REF-1781869121102-4040",
      "action": "confirm",
      "category": "collections",
      "payment_type": "card-acq",
      "payment_type_data": {
        "payment_country": "US",
        "auth_model": "3ds_required",
        "last_four_digits": "7223"
      },
      "status": "failed",
      "entity_id": "01K8QZHTWHNGS2Y21HXB36XXXX",
      "account_id": "01K8TN588BZKJHZ3VHR2BXXXX",
      "payment_intent_id": "01KVFTXH5G40ER6VJPVBTZXXXX",
      "return_url": "https://app.nuvion.co",
      "created": 1781869279195
    }
  }
}

Return a 2xx response to acknowledge receipt. See Webhooks for delivery and retry details.

Retrieve a payment intent

GET /payment-intents/{id} Returns a single Payment Intent.

string

required

Payment Intent ID.

curl https://api.nuvion.dev/payment-intents/01HXYZ7K3M9PQRST4UVWXY2Z6 \
  -H "Authorization: Bearer $NUVION_API_KEY"

List payment intents

GET /payment-intents Returns a paginated list of Payment Intents.

string

Filter by status.

string

Filter by client reference.

string

Filter by currency.

string

Filter by account.

string

Filter by creation date start.

string

Filter by creation date end.

number

Maximum number of records to return.

string

Cursor for the next page.

string

Cursor for the previous page.

curl "https://api.nuvion.dev/payment-intents?status=completed&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Cancel a payment intent

PATCH /payment-intents/{id} Cancels a Payment Intent that has not been confirmed. Only intents with status: "requires_action" can be cancelled.

string

required

Payment Intent ID.

string

required

Must be cancel.

string

Cancellation reason. 1–100 characters.

curl -X PATCH https://api.nuvion.dev/payment-intents/01HXYZ7K3M9PQRST4UVWXY2Z6 \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "cancel",
    "reason": "Customer abandoned checkout"
  }'

Retrieve an intent action

GET /intent-actions/{id} Returns a single Intent Action.

string

required

Intent Action ID.

curl https://api.nuvion.dev/intent-actions/01HACT9012EFGH \
  -H "Authorization: Bearer $NUVION_API_KEY"

List intent actions

GET /intent-actions Returns a paginated list of Intent Actions.

string

Filter by currency.

string

Filter by client reference.

string

Filter by payment type. e.g. card-acq.

string

Filter by status.

string

Filter by Payment Intent ID.

string

Filter by account.

string

Filter by creation date start.

string

Filter by creation date end.

number

Maximum number of records to return.

string

Cursor for the next page.

string

Cursor for the previous page.

curl "https://api.nuvion.dev/intent-actions?payment_intent_id=01HXYZ7K3M9PQRST4UVWXY2Z6" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Verify an intent action

POST /intent-verifications/{id} Rechecks an Intent Action that has not reached a final status. If the action is already completed or failed, the current action is returned.

string

required

Intent Action ID.

curl -X POST https://api.nuvion.dev/intent-verifications/01HACT9012EFGH \
  -H "Authorization: Bearer $NUVION_API_KEY"

​The Payment Intent object

​Payment intent statuses

​The Intent Action object

​Intent action statuses

​Retrieve intent_action

​Card data encryption

​Create a payment intent

​Request parameters

​Request

​Response

​Create and confirm in one request

​Confirm a payment intent

​Request parameters

​Card request

​Apple Pay request

​Response

​Payment intent webhooks

​Retrieve a payment intent

​List payment intents

​Cancel a payment intent

​Retrieve an intent action

​List intent actions

​Verify an intent action

The Payment Intent object

Payment intent statuses

The Intent Action object

Intent action statuses

Retrieve intent_action

Card data encryption

Create a payment intent

Request parameters

Request

Response

Create and confirm in one request

Confirm a payment intent

Request parameters

Card request

Apple Pay request

Response

Payment intent webhooks

Retrieve a payment intent

List payment intents

Cancel a payment intent

Retrieve an intent action

List intent actions

Verify an intent action