WooshPay OpenAPI
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Product DocumentAPI ReferenceJS SDK ReferenceSaaS Platform Integration
Back to WooshPay Website
  1. Invoices
  • API Introduction
  • Error Code
  • Payment Intents
    • Create a PaymentIntent
      POST
    • Update a PaymentIntent
      POST
    • Cancel a PaymentIntent
      POST
    • Capture a PaymentIntent
      POST
    • Confirm a PaymentIntent
      POST
    • Retrieve a PaymentIntent
      GET
    • List all PaymentIntents
      GET
    • Search PaymentIntents
      GET
  • Charges
    • Retrieve a charge
      GET
    • List all charges
      GET
  • Payment Methods
    • Create a PaymentMethod
      POST
    • Retrieve a PaymentMethod
      GET
    • Retrieve a Customer's PaymentMethod
      GET
    • Update a PaymentMethod
      POST
    • List PaymentMethods
      GET
    • List a Customer's PaymentMethods
      GET
    • Attach a PaymentMethod to a Customer
      POST
    • Detach a PaymentMethod from a Customer
      POST
  • Refunds
    • Create a refund
    • Retrieve a refund
  • Webhooks
    • Create a Webhook
    • List All Webhooks
    • Retrieve a Webhook
    • Delete a Webhook
    • Update a Webhook
  • Events
    • Types of events
    • Retrieve an event
  • Files
    • Files
    • Create a file
    • Retrieve a file
  • Disputes
    • Retrieve a dispute
    • Update a dispute
    • Close a dispute
    • List all disputes
  • Payouts
    • Beneficiary
      • Create a beneficiary
      • Retrieve a beneficiary
      • List all beneficiaries
      • Update a beneficiary
      • Delete a beneficiary
    • Payouts
      • Create a payout
      • Retrieve a Payout
      • Update a Payout
      • List All Payouts
  • Balance
    • Get balance
  • Products
    • Create a Product
    • Retrieve a product
    • Update a product
    • List all products
  • Prices
    • Create a price
    • Retrieve a price
    • Update a price
  • Payment Links
    • Create a payment link
    • Update a payment link
    • Retrieve payment link
    • List all payment links
    • Retrieve a payment link's line items
  • Checkout
    • Create a Session
    • Expire a Session
    • Retreive a Session
    • List All Checkout Sessions
    • Retrieve a Checkout Session's line items
  • Customers
    • Create a customer
    • Retrieve a customer
    • Update a customer
  • Invoices
    • Setup Intents
      • Create a SetupIntent
      • Retrieve a SetupIntent
      • Cancel a SetupIntent
      • List all SetupIntents
      • List all SetupAttempts
      • Update a SetupIntent
      • Confirm a SetupIntent
    • Create an invoice
      POST
    • Retrieve an invoice
      GET
    • Finalize an invoice
      POST
    • Send an invoice for manual payment
      POST
    • Delete a draft invoice
      GET
    • Void an invoice
      POST
    • List all invoices
      GET
    • Pay an invoice
      POST
  • Invoice Items
    • Create an invoice item
    • Retrieve an invoice item
  • Invoice Line Item
    • Bulk add invoice line items
  • Subscriptions
    • Create a subscription
    • Retrieve a subscription
    • Update a subscription
    • Cancel a subscription
    • List subscriptions
  • Subscription Items
    • Create a subscription item
    • Retrieve a subscription item
    • Delete a subscription item
  • Issuing
    • Authorizations
      • Retrieve an authorization
      • List all authorization
    • Cardholders
      • Create a cardholder
      • Update a cardholder
      • Retrieve a cardholder
      • List all cardholders
    • Cards
      • Create a card
      • Update a card
      • Retrieve a card
      • List all cards
      • Retrieve card remaining limits
    • Transactions
      • Update a transaction
      • Retrieve a transaction
      • List all transactions
  • Coupons
    • Create a Coupon
    • Retrieve a coupon
    • Delete a coupon
  • Promotion Code
    • Create a promotion code
    • Update a promotion code
  • Accounts
    • Retrieve account's paymentmethods
  • Fx Quote
    • Create an FX Quote
  1. Invoices

Finalize an invoice

Developing
POST
/v1/invoices/{id}/finalize
Wooshpay automatically finalizes drafts before sending and attempting payment on invoices. However, if you’d like to finalize a draft invoice manually, you can do so using this method.
Returns an invoice object with status=open.

Request

Authorization
Send your HTTP requests with an
Authorization
header that contains the word Basic followed by a space and a base64-encoded string username:password
Example:
Authorization: Basic *****************
Path Params
id
string 
required
Header Params
Accept
string 
required
Default:
application/json
Content-Type
string 
required
Default:
application/json
Body Params application/json
auto_advance
boolean 
optional
Controls whether Wooshpay performs automatic collection of the invoice. If false, the invoice’s state doesn’t automatically advance without an explicit action.
Example
{
    "auto_advance": true
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://apitest.wooshpay.com/v1/invoices//finalize' \
--header 'Accept;' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Og==' \
--data-raw '{
    "auto_advance": true
}'

Responses

🟢200OK
application/json
Body
id
string 
optional
currency
string 
optional
Three-letter ISO currency code
customer
string 
optional
The ID of the customer who will be billed.
object
string 
optional
String representing the object’s type. Objects of the same type share the same value.
auto_advance
boolean 
optional
If false, the invoice’s state doesn’t automatically advance without an explicit actio
charge
string 
optional
ID of the latest charge generated for this invoice, if any.
collection_method
string 
optional
Either charge_automatically, or send_invoice
description
string 
optional
An arbitrary string attached to the object. Often useful for displaying to users.
hosted_invoice_url
string 
optional
The URL for the hosted invoice page, which allows customers to view and pay an invoice. If the invoice has not been finalized yet, this will be null.
lines
object 
optional
list. The individual line items that make up the invoice. lines is sorted as follows: (1) pending invoice items (including prorations) in reverse chronological order, (2) subscription items in reverse chronological order, and (3) invoice items added after invoice creation in chronological order.
object
string 
optional
value is "list"
data
array [object {18}] 
optional
contains: line_item object. Details about each object.
has_more
boolean 
optional
True if this list has another page of items after this one that can be fetched
url
string 
optional
The URL where this list can be accessed.
metadata
object 
optional
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
payment_intent
string 
optional
EXPANDABLE. The PaymentIntent associated with this invoice. The PaymentIntent is generated when the invoice is finalized, and can then be used to pay the invoice. Note that voiding an invoice will cancel the PaymentIntent.
period_end
string 
optional
timestamp. End of the usage period during which invoice items were added to this invoice.
period_start
string 
optional
timestamp. Start of the usage period during which invoice items were added to this invoice.
status
string 
optional
The status of the invoice, one of draft, open, paid, uncollectible, or void
subscription
string 
optional
EXPANDABLE. The subscription that this invoice was prepared for, if any.
account_country
string 
optional
The country of the business associated with this invoice, most often the business creating the invoice.
account_name
string 
optional
The public name of the business associated with this invoice, most often the business creating the invoice.
amount_due
integer 
optional
Final amount due at this time for this invoice. If the invoice’s total is smaller than the minimum charge amount, for example, or if there is account credit that can be applied to the invoice, the amount_due may be 0. If there is a positive starting_balance for the invoice (the customer owes money), the amount_due will also take that into account. The charge that gets generated for the invoice will be for the amount specified in amount_due.
amount_paid
integer 
optional
amount_precision
integer 
optional
This field controls the precision of the amount displayed on the invoice. If amount_precision is set to 3, it means the smallest decimal for the amount parameter is 3. This field only affects the display. For actual deductions, please refer to the minimum unit of the supported currency. The default value is the minimum unit of the currency.
billing_reason
enum<string> 
optional
Indicates the reason why the invoice was created. manual: Unrelated to a subscription, for example, created via the invoice editor. subscription: No longer in use. Applies to subscriptions from before May 2018 where no distinction was made between updates, cycles, and thresholds. subscription_create: A new subscription was created. subscription_cycle: A subscription advanced into a new period. subscription_threshold: A subscription reached a billing threshold. subscription_update: A subscription was updated. upcoming: Reserved for simulated invoices, per the upcoming invoice endpoint.
Allowed values:
manualsubscriptionsubscription_createsubscription_cyclesubscription_thresholdsubscription_updateupcoming
created
integer 
optional
Time at which the object was created. Measured in seconds since the Unix epoch.
custom_fields
array [object {2}] 
optional
A list of up to 4 custom fields to be displayed on the invoice.
name
string 
optional
The name of the custom field.
value
string 
optional
The value of the custom field.
customer_address
object (Address) 
optional
The customer’s address. Until the invoice is finalized, this field will equal customer.address. Once the invoice is finalized, this field will no longer be updated.
city
string 
optional
City, district, suburb, town, or village.
country
string 
optional
Two-letter country code (ISO 3166-1 alpha-2 ).
line1
string 
optional
Address line 1 (e.g., street, PO Box, or company name).
line2
string 
optional
Address line 2 (e.g., apartment, suite, unit, or building).
postal_code
string 
optional
ZIP or postal code.
state
string 
optional
State, county, province, or region.
customer_email
string 
optional
The customer’s email. Until the invoice is finalized, this field will equal customer.email. Once the invoice is finalized, this field will no longer be updated.
customer_name
string 
optional
The customer’s name. Until the invoice is finalized, this field will equal customer.name. Once the invoice is finalized, this field will no longer be updated.
customer_phone
string 
optional
The customer’s phone number. Until the invoice is finalized, this field will equal customer.phone. Once the invoice is finalized, this field will no longer be updated.
customer_shipping
object 
optional
address
object 
optional
name
string 
optional
phone
string 
optional
default_payment_method
string 
optional
ID of the default payment method for the invoice. It must belong to the customer associated with the invoice. If not set, defaults to the subscription’s default payment method, if any, or to the default payment method in the customer’s invoice settings
due_date
string 
optional
timestamp.The date on which payment for this invoice is due. This value will be null for invoices where collection_method=charge_automatically.
effective_at
string 
optional
The date when this invoice is in effect. Same as finalized_at unless overwritten. When defined, this value replaces the system-generated ‘Date of issue’ printed on the invoice PDF and receipt.
footer
string 
optional
Footer displayed on the invoice.
from_invoice
object 
optional
action
string 
required
The relation between the new invoice and the original invoice. Currently, only ‘revision’ is permitted
invoice
string 
required
The id of the invoice that will be cloned.
invoice_pdf
string 
optional
last_finalization_error
object 
optional
The error encountered during the previous attempt to finalize the invoice. This field is cleared when the invoice is successfully finalized.
type
string 
optional
code
string 
optional
message
string 
optional
param
string 
optional
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.
payment_method_type
string 
optional
If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors.
latest_revision
string 
optional
The ID of the most recent non-draft revision of this invoice
livemode
boolean 
optional
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
next_payment_attempt
string 
optional
The time at which payment will next be attempted. This value will be null for invoices where collection_method=send_invoice.
number
string 
optional
A unique, identifying string that appears on emails sent to the customer for this invoice. This starts with the customer’s unique invoice_prefix if it is specified.
paid
boolean 
optional
Whether payment was successfully collected for this invoice.
paid_out_of_band
boolean 
optional
Returns true if the invoice was manually marked paid, returns false if the invoice hasn’t been paid yet or was paid on Wooshpay.
payment_settings
object 
optional
default_mandate
string 
optional
ID of the mandate to be used for this invoice. It must correspond to the payment method used to pay the invoice, including the invoice’s default_payment_method or default_source, if set.
payment_method_options
object 
optional
Payment-method-specific configuration to provide to the invoice’s PaymentIntent.
payment_method_types
string 
optional
The list of payment method types (e.g. card) to provide to the invoice’s PaymentIntent.
receipt_number
string 
optional
This is the transaction number that appears on email receipts sent for this invoice.
starting_balance
string 
optional
Starting customer balance before the invoice is finalized. If the invoice has not been finalized yet, this will be the current customer balance. For revision invoices, this also includes any customer balance that was applied to the original invoice.
statement_descriptor
string 
optional
Extra information about an invoice for the customer’s credit card statement.
status_transitions
object 
optional
The timestamps at which the invoice status was updated
finalized_at
string 
optional
timestamp
marked_uncollectible_at
string 
optional
timestamp
paid_at
string 
optional
timestamp
voided_at
string 
optional
timestamp
subscription_details
object 
optional
Details about the subscription that created this invoice.
metadata
object 
optional
test_clock
string 
optional
ID of the test clock this invoice belongs to.
threshold_reason
object 
optional
If billing_reason is set to subscription_threshold this returns more information on which threshold rules triggered the invoice.
amount_gte
string 
optional
item_reasons
array [object {2}] 
optional
total
integer 
optional
Total after discounts and taxes.
rounding_rule
enum<string> 
optional
If amount_precision is defined, this field is used to control rounding of the amount to the smallest unit supported by the currency.
Allowed values:
round_upround_down
Example
{
    "id": "string",
    "currency": "string",
    "customer": "string",
    "object": "string",
    "auto_advance": true,
    "charge": "string",
    "collection_method": "string",
    "description": "string",
    "hosted_invoice_url": "string",
    "lines": {
        "object": "string",
        "data": [
            {
                "id": "string",
                "object": "string",
                "amount": 0,
                "currency": "string",
                "description": "string",
                "metadata": {},
                "period": {
                    "end": "string",
                    "start": "string"
                },
                "price": {
                    "id": "string",
                    "object": "string",
                    "active": true,
                    "billing_scheme": "per_unit",
                    "created": 0,
                    "currency": "string",
                    "livemode": true,
                    "lookup_key": "string",
                    "metadata": {},
                    "nickname": "string",
                    "product": "string",
                    "type": "one_time",
                    "unit_amount": 0,
                    "recurring": {
                        "interval": "day",
                        "interval_count": 0,
                        "usage_type": "licensed"
                    },
                    "tiers": [
                        {
                            "up_to": "string",
                            "flat_amount": "string",
                            "unit_amount": "string"
                        }
                    ]
                },
                "unit_amount": "string",
                "quantity": 0,
                "invoice_item": "string",
                "type": "string",
                "livemode": true,
                "subscription": "string",
                "subscription_item": "string",
                "unit_amount_excluding_tax": 0,
                "discount_amounts": [
                    {
                        "amount": "string",
                        "discount": "string"
                    }
                ],
                "discountable": true
            }
        ],
        "has_more": true,
        "url": "string"
    },
    "metadata": {},
    "payment_intent": "string",
    "period_end": "string",
    "period_start": "string",
    "status": "string",
    "subscription": "string",
    "account_country": "string",
    "account_name": "string",
    "amount_due": 0,
    "amount_paid": 0,
    "amount_precision": 0,
    "billing_reason": "manual",
    "created": 0,
    "custom_fields": [
        {
            "name": "string",
            "value": "string"
        }
    ],
    "customer_address": {
        "city": "string",
        "country": "string",
        "line1": "string",
        "line2": "string",
        "postal_code": "string",
        "state": "string"
    },
    "customer_email": "string",
    "customer_name": "string",
    "customer_phone": "string",
    "customer_shipping": {
        "address": {
            "city": "string",
            "country": "string",
            "line1": "string",
            "line2": "string",
            "postal_code": "string",
            "state": "string"
        },
        "name": "string",
        "phone": "string"
    },
    "default_payment_method": "string",
    "due_date": "string",
    "effective_at": "string",
    "footer": "string",
    "from_invoice": {
        "action": "string",
        "invoice": "string"
    },
    "invoice_pdf": "string",
    "last_finalization_error": {
        "type": "string",
        "code": "string",
        "message": "string",
        "param": "string",
        "payment_method_type": "string"
    },
    "latest_revision": "string",
    "livemode": true,
    "next_payment_attempt": "string",
    "number": "string",
    "paid": true,
    "paid_out_of_band": true,
    "payment_settings": {
        "default_mandate": "string",
        "payment_method_options": {
            "card": {
                "request_three_d_secure": "string"
            }
        },
        "payment_method_types": "string"
    },
    "receipt_number": "string",
    "starting_balance": "string",
    "statement_descriptor": "string",
    "status_transitions": {
        "finalized_at": "string",
        "marked_uncollectible_at": "string",
        "paid_at": "string",
        "voided_at": "string"
    },
    "subscription_details": {
        "metadata": {}
    },
    "test_clock": "string",
    "threshold_reason": {
        "amount_gte": "string",
        "item_reasons": [
            {
                "line_item_ids": "string",
                "usage_gte": "string"
            }
        ]
    },
    "total": 0,
    "rounding_rule": "round_up"
}
Previous
Retrieve an invoice
Next
Send an invoice for manual payment
Built with