Documentation Index Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
Use this file to discover all available pages before exploring further.
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 Unique payment intent identifier.
ISO 4217 currency code. e.g. USD, GBP, EUR.
Amount in the smallest currency unit. 5000 = $50.00 USD.
Your unique order or transaction reference.
Optional human-readable payment description.
Intent status. One of requires_action, processing, completed, cancelled, or failed.
Reason for the current status. Present when a payment fails or is cancelled with a reason.
Entity that owns the payment intent.
Account credited when the payment completes.
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_actionIntent created and ready to be confirmed. processingA confirmation action is being processed. completedPayment completed successfully. cancelledIntent was cancelled before completion. failedPayment failed. Check status_reason.
The Intent Action object Unique intent action identifier.
Currency inherited from the payment intent.
Payment amount inherited from the payment intent.
Fee charged for the payment in the smallest currency unit.
Amount charged for the payment.
Amount refunded so far in the smallest currency unit.
Client reference inherited from the payment intent.
Action performed. Currently confirm.
Payment category. Currently collections.
Payment method. One of card-acq or applepay-acq.
Payment method data returned for the action. Sensitive card details are never returned.
Action status. One of pending, pending_user_action, completed, or failed.
Reason for the current status. Present when a payment fails.
Entity that owns the intent action.
Account credited when the payment completes.
Payment Intent linked to this action.
true when the customer must complete a redirect or challenge.
Next step for the customer when requires_action is true.
URL the customer is redirected to after authentication.
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 pendingAction created and being processed. pending_user_actionCustomer must complete authentication. completedPayment completed successfully. failedPayment failed. Check status_reason.
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" }
Card PAN. 13–19 digits. Spaces are ignored after decryption.
Expiry month, 1–12 or zero-padded 01–12.
Four-digit expiry year. The expiry date must not be in the past.
Card verification value. 3 or 4 digits.
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-intentsCreates a payment intent for a card payment.
Request parameters ISO 4217 currency code. e.g. USD.
Amount in the smallest currency unit. 5000 = $50.00 USD.
Account to credit when the payment completes.
Unique order or transaction reference. 1–100 characters. The same reference cannot be reused for the same account.
A human-readable payment description. Maximum 250 characters.
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" }, "auth_model": "3ds_disabled" }, "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" : { "auth_model" : "3ds_disabled" , "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-actionsConfirms a payment intent with card or Apple Pay payment data.
Request parameters Payment Intent to confirm. The intent must have status: "requires_action".
Confirmation action details.
intent_action.payment_type
Payment method. One of card-acq or applepay-acq.
intent_action.payment_type_data
Payment method data.
intent_action.payment_type_data.data
Encrypted Base64 card data. Required for card-acq; omit for applepay-acq.
intent_action.payment_type_data.billing_address
Billing address. For applepay-acq, only country is required. Show billing_address fields
First line of the billing address. Required for card-acq.
Billing city. Required for card-acq.
Billing state, region, or province. Required for card-acq.
Two-letter country code. e.g. US.
Apartment, suite, or second address line.
intent_action.payment_type_data.auth_model
Card authentication model. One of 3ds_required or 3ds_disabled. Defaults to 3ds_required.
intent_action.payment_type_data.browser_info
Browser data for 3DS authentication. Required unless auth_model is 3ds_disabled.
Customer details for the payment. Customer phone number in E.164 format, when available.
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", "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.completedPayment completed successfully payment_intent.failedPayment failed payment_intent.cancelledPayment Intent cancelled before confirmation
{ "event" : "payment_intent.completed" , "data" : { "id" : "01HXYZ7K3M9PQRST4UVWXY2Z6" , "currency" : "USD" , "amount" : 5000 , "reference" : "order_abc123" , "description" : "Order #1042" , "status" : "completed" , "entity_id" : "ent_01HXYZ1234ABCD" , "account_id" : "acc_01HXYZ5678EFGH" , "created" : 1735725600000 } }
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.
curl https://api.nuvion.dev/payment-intents/01HXYZ7K3M9PQRST4UVWXY2Z6 \ -H "Authorization: Bearer $NUVION_API_KEY "
List payment intents GET /payment-intentsReturns a paginated list of Payment Intents.
Filter by client reference.
Filter by creation date start.
Filter by creation date end.
Maximum number of records to return.
Cursor for the next page.
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.
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.
curl https://api.nuvion.dev/intent-actions/01HACT9012EFGH \ -H "Authorization: Bearer $NUVION_API_KEY "
List intent actions GET /intent-actionsReturns a paginated list of Intent Actions.
Filter by client reference.
Filter by payment type. e.g. card-acq.
Filter by Payment Intent ID.
Filter by creation date start.
Filter by creation date end.
Maximum number of records to return.
Cursor for the next page.
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.
curl -X POST https://api.nuvion.dev/intent-verifications/01HACT9012EFGH \ -H "Authorization: Bearer $NUVION_API_KEY "
