--- title: "Pay Invoice" source_url: https://docs.rapyd.net/en/pay-invoice.html lang: en --- # Pay Invoice Make a payment against an invoice. This method triggers the following webhooks: - [Invoice Payment Created Webhook](https://docs.rapyd.net/en/invoice-payment-created-webhook.md "Invoice Payment Created Webhook") - This webhook contains the same information as the response. - [Invoice Finalized Webhook](https://docs.rapyd.net/en/invoice-finalized-webhook.md "Invoice Finalized Webhook") - [Invoice Payment Succeeded Webhook](https://docs.rapyd.net/en/invoice-payment-succeeded-webhook.md "Invoice Payment Succeeded Webhook") The following asynchronous webhooks provide information about later changes to the Invoice object: - [Payment Completed Webhook](https://docs.rapyd.net/en/payment-completed-webhook.md "Payment Completed Webhook") - [Invoice Payment Failed Webhook](https://docs.rapyd.net/en/invoice-payment-failed-webhook.md "Invoice Payment Failed Webhook") - [Payment Failed Webhook](https://docs.rapyd.net/en/payment-failed-webhook.md "Payment Failed Webhook") Depending on the request values, some of these webhooks are triggered synchronously. > **Note:** > > - Before you pay an invoice with a token for a payment method, verify that the value of `is_tokenizable` is **true**. > - If the payment method category is **card**, certain operations require 3DS authentication. To simulate this authentication in the sandbox, use the URL from the `redirect_url` field that appears in the response and in [Invoice Payment Created Webhook](https://docs.rapyd.net/en/invoice-payment-created-webhook.md "Invoice Payment Created Webhook") and [Payment Succeeded Webhook](https://docs.rapyd.net/en/payment-succeeded-webhook.md "Payment Succeeded Webhook"). See [Simulating 3DS Authentication](https://docs.rapyd.net/en/simulating-3ds-authentication.md "Simulating 3DS Authentication"). > - A **card** payment that requires 3DS authentication must be authenticated within 15 minutes. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Invoice Errors](https://docs.rapyd.net/en/invoice-errors.md "Invoice Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). ### Parameters ### Request Path Parameters - - invoice - ID of the invoice you want to pay. String starting with **invoice_**. ### Request Body Parameters - - payment_method - ID of the payment method for paying the invoice. If not included in the body, then the customer's default payment method is used. ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Response Parameters - - attempt_count - Total number of attempts made to pay this invoice. - - attempted - Indicates whether an attempt has been made to pay the invoice automatically. - - automatic_attempt_count - Number of automatic attempts that Rapyd made to retry paying this invoice if it failed. - - billing - Determines the method of billing at the end of the billing cycle. Set to **pay_automatically** - Rapyd generates a `payment` object, then attempts to pay it using the designated payment method. - - billing_reason - The reason for billing. One of the following: - **subscription_cycle** - A new cycle for the subscription. - **subscription_create** - A new subscription has been created. - **manual** - Customer was billed manually. - **upcoming** - Customer has an upcoming billing invoice. - - created_at - The time the invoice was created, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - Three-letter ISO 4217 currency code for the currency used in all fields that refer to a monetary amount. - - customer - ID of the customer that pays this invoice. String starting with **cus_**. - - days_until_due - Number of days the customer has for paying this invoice. Integer. - - description - Description of the invoice. - - discount - Describes the discount that applies to this invoice. The source of the discount is one of the following: - If the invoice is generated manually, the discount is taken from the Customer object. - If the invoice is generated automatically from a subscription, the discount is taken from the Subscription object if it is defined there. Otherwise, it is taken from the Customer object. - - discount_amount - The amount of the discount that was applied to this invoice. - - due_date - The date payment is due on this invoice. This value is calculated from the date the invoice is created, plus the number of days specified in the `days_until_due` field. Relevant when `billing` is **send_invoice**. Format is in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - id - ID of the invoice. String starting with **invoice_**. - - lines - The individual line items that make up the invoice. These items are added with [Create Invoice](https://docs.rapyd.net/en/create-invoice.md "Create Invoice") or [Update Invoice](https://docs.rapyd.net/en/update-invoice.md "Update Invoice"). For details o the fields in the 'invoice_item' object, see [Create Invoice Item](https://docs.rapyd.net/en/create-invoice-item.md "Create Invoice Item"). - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - next_payment_attempt - The time when the next payment attempt will be made, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - number - Invoice number, starting with the `invoice_prefix` specified in the Customer object. - - payment - The 'payment' object that was generated for this invoice. For details of the fields in the 'payment' object, see [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment"). - - payment_fields - Additional `payment_options`. - - payment_method - ID of the payment method for paying the invoice. - - payout - Reserved. - - payout_fields - Reserved. - - period_end - Last date in the period covered by the invoice, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - period_start - First date in the period covered by the invoice, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - statement_descriptor - Description of the invoice for the customer's credit card statement. Limited to 22 characters. - - status - An invoice moves through a series of statuses. - **draft** - Starting status for all invoices. The invoice can still be edited or deleted. The subscription's 'simultaneous_invoice' field determines when the status automatically moves to **open**. At any time, payment of the invoice via the 'Pay Invoice' method can move the invoice to another status. - **deleted** - An invoice can be deleted only when its status is **draft**. This action is usually done after an invoice is created due to an error. - **open** - The invoice has been finalized, and the system is now waiting for the payment to be completed by the customer. The invoice can no longer be edited. - **paid** - The paid status is used for invoices that are paid. Invoices are automatically marked as paid when payments are processed by Rapyd. - **void** - Voiding is similar to deleting an invoice, but keeps a record of when it was created, finalized, and voided. Invoices with a void status cannot be paid. - **uncollectible** - This invoice cannot be paid by the customer. - - subscription - ID of the subscription that generates charges to this customer. String starting with **sub_**. - - subtotal - Total of all line items before discount and before tax. Decimal. - - tax - The amount of tax charged. Decimal. This is calculated as**T = R x (S - D)**, where: - **T** is the tax. - **R** is the tax rate in `tax_percent`. - **S** is the subtotal. - **D** is the discount. - - tax_percent - The percentage tax rate that is applied to the subtotal of the invoice, after subtracting all discounts. Decimal, up to four decimal places. Range: 0-100 - - total - Total after discount and tax. Decimal. - - type - The type of the subscription: **payment** ### Code Samples - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string invoice = "invoice_f387777eaa23ff864e2a8fced2455ef6"; string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/invoices/{invoice}/pay"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest( 'POST', '/v1/invoices/invoice_f387777eaa23ff864e2a8fced2455ef6/pay' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('post', "/v1/invoices/invoice_f387777eaa23ff864e2a8fced2455ef6/pay"); var_dump($object); } catch(Exception $e) { echo "Error => $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request result = make_request(method='post', path='/v1/invoices/invoice_f387777eaa23ff864e2a8fced2455ef6/pay') pprint(result) ``` - /v1/invoices/:invoice/pay - Pay Invoice - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_3c69b5228f548953a4da8cb5f80d79b8/pay' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "4a9ddcbf-0ed4-4441-8af3-eeaaeb7bfdbd" }, "data": { "id": "invoice_3c69b5228f548953a4da8cb5f80d79b8", "attempt_count": 0, "billing": "pay_automatically", "billing_reason": "manual", "created_at": 1764745257, "currency": "USD", "customer": "cus_4e25112ac20e144ad073a614dc46934b", "description": "", "discount": null, "due_date": 1767337257, "days_until_due": 30, "metadata": {}, "payment_method": "card_b9548d9b53a565b2315fecdc6c87f158", "payment": null, "payout": null, "payment_fields": null, "period_end": 0, "period_start": 0, "lines": [], "statement_descriptor": "", "subscription": "", "discount_amount": 0, "subtotal": 0, "tax": 0, "tax_percent": 0, "total": 0, "status": "paid", "payout_fields": null, "type": "payment" } } ``` - Bad Request - Status Not Draft - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_90be94b2416dfb41b7458ad551e62e0/pay' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "ERROR_UPDATE_NOT_DRAFT_INVOICE", "status": "ERROR", "message": "The request tried to a update an invoice but the invoice is not draft. Can only update draft invoice. The request was rejected.", "response_code": "ERROR_UPDATE_NOT_DRAFT_INVOICE", "operation_id": "0cf27984-c881-4b23-a97d-55eaec3f46c3" } } ``` - Bad Request - Invoice Not Found - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/invoices/invoice_90be94b2416dfb41b7458ad551e62e0/pay' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '' ``` - ```json { "status": { "error_code": "ERROR_GET_INVOICE", "status": "ERROR", "message": "The request tried to retrieve an invoice, but the invoice was not found. The request was rejected. Corrective action: Use a valid invoice ID.", "response_code": "ERROR_GET_INVOICE", "operation_id": "a201da53-3a4f-4ff2-8545-101d18c1e970" } } ```