paypal.invoices
Module paypal.invoices
Definitions

ballerinax/paypal.invoices Ballerina library
Overview
PayPal is a global online payment platform enabling individuals and businesses to securely send and receive money, process transactions, and access merchant services across multiple currencies.
The ballerinax/paypal.invoices
package provides a Ballerina connector for interacting with the PayPal Invoicing API v2, allowing you to create, send, manage, and track invoices in your Ballerina applications.
Setup guide
To use the PayPal Invoices connector, you must have access to a PayPal Developer account.
Step 1: Create a business account
-
Open the PayPal Developer Dashboard.
-
Click on "Sandbox Accounts" under "Testing Tools".
-
Create a Business account
Note: Some PayPal options and features may vary by region or country; check availability before creating an account.
Step 2: Create a REST API app
-
Navigate to the "Apps and Credentials" tab and create a new merchant app.
Provide a name for the application and select the Business account you created earlier.
Step 3: Obtain Client ID and Client Secret
-
After creating your new app, you will see your Client ID and Client Secret. Make sure to copy and securely store these credentials.
Quickstart
To use the paypal.invoices
connector in your Ballerina application, update the .bal
file as follows:
Step 1: Import the module
Import the paypal.invoices
module.
import ballerinax/paypal.invoices as paypal;
Step 2: Instantiate a new connector
- Create a
Config.toml
file and configure the obtained credentials in the above steps as follows:
clientId = "<test-client-id>" clientSecret = "<test-client-secret>" serviceUrl = "<paypal-service-url>" tokenUrl = "<paypal-token-url>"
- Create a
paypal.invoices:ConnectionConfig
with the obtained credentials and initialize the connector with it.
configurable string clientId = ?; configurable string clientSecret = ?; configurable string merchantEmail = ?; configurable string serviceUrl = ?; configurable string tokenUrl = ?;
final paypal.invoices:Client paypalInvoices = check new ({ auth: { clientId, clientSecret, tokenUrl } }, serviceUrl);
Step 3: Invoke the connector operation
Now, utilize the available connector operations.
Create a draft invoice
public function main() returns error? { paypal.invoices:Invoice invoice = { detail: { invoice_number: "INV-001", currency_code: "USD" }, invoicer: { name: { given_name: "John", surname: "Doe" }, email_address: "merchant@example.com" }, primary_recipients: [{ billing_info: { name: { given_name: "Jane", surname: "Smith" }, email_address: "customer@example.com" } }], items: [{ name: "Product or Service", quantity: "1", unit_amount: { currency_code: "USD", value: "100.00" } }] }; paypal.invoices:Invoice response = check paypalInvoices->/invoices.post(invoice); }
Step 4: Run the Ballerina application
bal run
Examples
The PayPal Invoices
connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
-
Record invoice: Create and manage draft invoices with detailed billing information and line items.
-
Send and cancel invoice: Send invoices to customers and handle cancellation scenarios.
Clients
paypal.invoices: Client
Use the Invoicing API to create, send, and manage invoices. You can also use the API or webhooks to track invoice payments. When you send an invoice to a customer, the invoice moves from draft to payable state. PayPal then emails the customer a link to the invoice on the PayPal website. Customers with a PayPal account can log in and pay the invoice with PayPal. Alternatively, customers can pay as a guest with a debit card or credit card. For more information, see the Invoicing Overview and the Invoicing Integration Guide.
Constructor
Gets invoked to initialize the connector
.
init (ConnectionConfig config, string serviceUrl)
- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api-m.sandbox.paypal.com/v2/invoicing" - URL of the target service
get invoices
function get invoices(map<string|string[]> headers, *InvoicesListQueries queries) returns Invoices|error
List invoices
Parameters
- queries *InvoicesListQueries - Queries to be sent with the request
Return Type
post invoices
function post invoices(Invoice payload, InvoicesCreateHeaders headers) returns Invoice|error
Create draft invoice
Parameters
- payload Invoice - The invoice details which includes all information of the invoice like items, billing information
- headers InvoicesCreateHeaders (default {}) - Headers to be sent with the request
Return Type
post invoices/[string invoiceId]/send
function post invoices/[string invoiceId]/send(Notification payload, map<string|string[]> headers) returns LinkDescription|'202Response|error
Send invoice
Parameters
- payload Notification - The email or SMS notification to send to the payer when they send an invoice.
Return Type
- LinkDescription|'202Response|error - A successful request returns the HTTP
200 OK
when the invoice issue date is current date
post invoices/[string invoiceId]/remind
function post invoices/[string invoiceId]/remind(Notification payload, map<string|string[]> headers) returns error?
Send invoice reminder
Parameters
- payload Notification - The email or SMS notification that will be sent to the payer for reminder
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
post invoices/[string invoiceId]/cancel
function post invoices/[string invoiceId]/cancel(Notification payload, map<string|string[]> headers) returns error?
Cancel sent invoice
Parameters
- payload Notification - The email or SMS notification that will be sent to the payer on cancellation
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
post invoices/[string invoiceId]/payments
function post invoices/[string invoiceId]/payments(PaymentDetail payload, map<string|string[]> headers) returns PaymentReference|error
Record payment for invoice
Parameters
- payload PaymentDetail - The details of the payment to record against the invoice
Return Type
- PaymentReference|error - A successful request returns the HTTP
200 Created
status code and a reference to the recorded payment
delete invoices/[string invoiceId]/payments/[string transactionId]
function delete invoices/[string invoiceId]/payments/[string transactionId](map<string|string[]> headers) returns error?
Delete external payment
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
post invoices/[string invoiceId]/refunds
function post invoices/[string invoiceId]/refunds(RefundDetail payload, map<string|string[]> headers) returns RefundReference|error
Record refund for invoice
Parameters
- payload RefundDetail - The details of the refund to record against the invoice
Return Type
- RefundReference|error - A successful request returns the HTTP
200 Created
status code and a reference to the recorded refund
delete invoices/[string invoiceId]/refunds/[string transactionId]
function delete invoices/[string invoiceId]/refunds/[string transactionId](map<string|string[]> headers) returns error?
Delete external refund
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
post invoices/[string invoiceId]/generate-qr-code
function post invoices/[string invoiceId]/generate\-qr\-code(QrConfig payload, map<string|string[]> headers) returns error?
Generate QR code
Parameters
- payload QrConfig - Optional configuration parameters to adjust QR code width, height and the encoded URL
Return Type
- error? - A successful request returns the HTTP
200 OK
status code and a JSON response body that shows the QR code as a PNG image
post generate-next-invoice-number
function post generate\-next\-invoice\-number(InvoicingGenerateNextInvoiceNumberHeaders headers) returns InvoiceNumber|error
Generate invoice number
Parameters
- headers InvoicingGenerateNextInvoiceNumberHeaders (default {}) - Headers to be sent with the request
Return Type
- InvoiceNumber|error - A successful request returns the HTTP
200 OK
status code and a JSON response body that shows the next invoice number
get invoices/[string invoiceId]
Show invoice details
Return Type
put invoices/[string invoiceId]
function put invoices/[string invoiceId](Invoice payload, InvoicesUpdateHeaders headers, *InvoicesUpdateQueries queries) returns Invoice|error
Fully update invoice
Parameters
- payload Invoice - A representation of changes to make in the invoice
- headers InvoicesUpdateHeaders (default {}) - Headers to be sent with the request
- queries *InvoicesUpdateQueries - Queries to be sent with the request
Return Type
delete invoices/[string invoiceId]
Delete invoice
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
post search-invoices
function post search\-invoices(SearchData payload, map<string|string[]> headers, *InvoicesSearchInvoicesQueries queries) returns Invoices|error
Search for invoices
Parameters
- payload SearchData - The invoice search can be used to retrieve the invoices based on the search parameters
- queries *InvoicesSearchInvoicesQueries - Queries to be sent with the request
Return Type
get templates
function get templates(map<string|string[]> headers, *TemplatesListQueries queries) returns Templates|error
List templates
Parameters
- queries *TemplatesListQueries - Queries to be sent with the request
Return Type
post templates
Create template
Parameters
- payload Template -
Return Type
get templates/[string templateId]
Show template details
Return Type
put templates/[string templateId]
function put templates/[string templateId](Template payload, map<string|string[]> headers) returns Template|error
Fully update template
Parameters
- payload Template - A representation of changes to make in the template
Return Type
delete templates/[string templateId]
Delete template
Return Type
- error? - A successful request returns the HTTP
204 No Content
status code with no JSON response body
Records
paypal.invoices: '202Response
Fields
- links? LinkDescription[] -
paypal.invoices: AddressDetails
The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example, address_portable.address_line_1
is usually a combination of address_details.street_number
, street_name
, and street_type
Fields
- building_name? string - A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example, <code>Craven House</code>
- street_number? string - The street number
- street_type? string - The street type. For example, avenue, boulevard, road, or expressway
- sub_building? string - The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment
- delivery_service? string - The delivery service. Post office box, bag number, or post office name
- street_name? string - The street name. Just
Drury
inDrury Lane
paypal.invoices: AddressPortable
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute
Fields
- country_code CountryCode -
- admin_area_1? string - The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example,
CA
and notCalifornia
. Value, by country, is:<ul><li>UK. A county.</li><li>US. A state.</li><li>Canada. A province.</li><li>Japan. A prefecture.</li><li>Switzerland. A kanton.</li></ul>
- address_line_1? string - The first line of the address. For example, number or street. For example,
173 Drury Lane
. Required for data entry and compliance and risk checks. Must contain the full address
- admin_area_3? string - A sub-locality, suburb, neighborhood, or district. Smaller than
admin_area_level_2
. Value is:<ul><li>Brazil. Suburb, bairro, or neighborhood.</li><li>India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.</li></ul>
- address_details? AddressDetails -
- admin_area_2? string - A city, town, or village. Smaller than
admin_area_level_1
- address_line_3? string - The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as
next to Walmart
, or a landmark in an Indian address
- address_line_2? string - The second line of the address. For example, suite or apartment number
- admin_area_4? string - The neighborhood, ward, or district. Smaller than
admin_area_level_3
orsub_locality
. Value is:<ul><li>The postal sorting code for Guernsey and many French territories, such as French Guiana.</li><li>The fine-grained administrative levels in China.</li></ul>
- postal_code? string - The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code
paypal.invoices: AggregatedDiscount
The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent
Fields
- item_discount? Money -
- invoice_discount? Discount -
paypal.invoices: AmountRange
The amount range
Fields
- upper_amount Money -
- lower_amount Money -
paypal.invoices: AmountSummaryDetail
The invoice amount summary of item total, discount, tax total, and shipping
Fields
- breakdown? AmountWithBreakdown - The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any
- value? string - The value, which might be:<ul><li>An integer for currencies like
JPY
that are not typically fractional.</li><li>A decimal fraction for currencies likeTND
that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see Currency Codes
- currency_code? CurrencyCode -
paypal.invoices: AmountWithBreakdown
The breakdown of the amount. Includes total item amount, total tax amount, custom amount, and shipping and discounts, if any
Fields
- tax_total? Money -
- shipping? ShippingCost - The shipping fee for all items. Includes tax on shipping
- custom? CustomAmount - The custom amount to apply to an invoice. If you include a label, you must include a custom amount
- discount? AggregatedDiscount - The discount. Can be an item- or invoice-level discount, or both. Can be applied as a percent or amount. If you provide both amount and percent, amount takes precedent
- item_total? Money -
paypal.invoices: BillingInfo
The billing information of the invoice recipient. Includes name, address, email, phone, and language
Fields
- Fields Included from *ContactNameAddress
- business_name string
- name Name
- address AddressPortable
- anydata...
- Fields Included from *BillingInfoAllOf2
- email_address EmailAddress
- phones PhoneDetail[]
- additional_info string
- language Language
- anydata...
paypal.invoices: BillingInfoAllOf2
Fields
- email_address? EmailAddress - The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
- phones? PhoneDetail[] - The invoice recipient's phone numbers. Extension number is not supported.
- additional_info? string - Any additional information about the recipient.
- language? Language - The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code
paypal.invoices: BusinessName
The business name of the party
Fields
- business_name? string - Required. The business name of the party
paypal.invoices: Configuration
The invoice configuration details. Includes partial payment, tip, and tax calculated after discount
Fields
- Fields Included from *TemplateConfiguration
- tax_calculated_after_discount boolean
- partial_payment PartialPayment
- allow_tip boolean
- tax_inclusive boolean
- anydata...
- Fields Included from *ConfigurationAllOf2
- template_id string
- anydata...
paypal.invoices: ConfigurationAllOf2
Fields
- template_id string(default "PayPal system template") - The template ID. The template determines the layout of the invoice. Includes which fields to show and hide.
paypal.invoices: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth OAuth2ClientCredentialsGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nil
values are treated as optional, and absent fields are handled asnilable
types. Enabled by default.
paypal.invoices: ContactNameAddress
The contact information of the user. Includes name and address
Fields
- Fields Included from *BusinessName
- business_name string
- anydata...
- Fields Included from *ContactNameAddressAllOf2
- name Name
- address AddressPortable
- anydata...
paypal.invoices: ContactNameAddressAllOf2
Fields
- name? Name - The name of the party
- address? AddressPortable - The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute
paypal.invoices: CustomAmount
The custom amount to apply to an invoice. If you include a label, you must include a custom amount
Fields
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- label string - The label to the custom amount of the invoice
paypal.invoices: DateRange
The date range. Filters invoices by creation date, invoice date, due date, and payment date
Fields
- 'start DateNoTime - The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years
- end DateNoTime - The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years
paypal.invoices: DateTimeRange
The date and time range. Filters invoices by creation date, invoice date, due date, and payment date
Fields
- 'start DateTime - The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
- end DateTime - The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
paypal.invoices: Detail
The details of the invoice like notes, terms and conditions, memo, attachments
Fields
- reference? string - The reference data. Includes a post office (PO) number.
- currency_code CurrencyCode - The three-character ISO-4217 currency code that identifies the currency
- note? string - A note to the invoice recipient. Also appears on the invoice notification email.
- terms_and_conditions? string - The general terms of the invoice. Can include return or cancellation policy and other terms and conditions.
- memo? string - A private bookkeeping memo for the user.
- attachments? FileReference[] - An array of PayPal IDs for the files that are attached to an invoice.
paypal.invoices: Discount
The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total
Fields
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- percent? Percentage - The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as
19.99
paypal.invoices: FileReference
The file reference. Can be a file in PayPal MediaServ, PayPal DMS, or other custom store
Fields
- content_type? string - The Internet Assigned Numbers Authority (IANA) media type of the file
- create_time? DateTime -
- size? string - The size of the file, in bytes
- reference_url? string - The reference URL for the file
- id? string - The ID of the referenced file
paypal.invoices: Invoice
The invoice details which includes all information of the invoice like items, billing information
Fields
- amount? AmountSummaryDetail - The invoice amount summary of item total, discount, tax total, and shipping
- configuration? Configuration - The invoice configuration details. Includes partial payment, tip, and tax calculated after discount
- payments? Payments - An array of payments registered against the invoice
- gratuity? Money - The currency and amount for a financial transaction, such as a balance or payment due
- primary_recipients? RecipientInfo[] - The billing and shipping information. Includes name, email, address, phone and language
- refunds? Refunds - The invoicing refund details. Includes the refund type, date, amount, and method
- due_amount? Money -
- parent_id? string - The parent ID to an invoice that defines the group invoice to which the invoice is related
- invoicer? InvoicerInfo - The invoicer business information that appears on the invoice
- links? LinkDescription[] - An array of request-related HATEOAS links
- id? string - The ID of the invoice
- detail InvoiceDetail - The details of the invoice. Includes invoice number, date, payment terms, and audit metadata
- additional_recipients? EmailAddress[] - An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.<blockquote><strong>Note:</strong> Valid values are email addresses in the
additional_recipients
value associated with the invoice.</blockquote>
- items? Item[] - An array of invoice line item information
- status? InvoiceStatus - The status of the invoice
paypal.invoices: InvoiceDetail
The details of the invoice. Includes invoice number, date, payment terms, and audit metadata
Fields
- Fields Included from *Detail
- reference string
- currency_code CurrencyCode
- note string
- terms_and_conditions string
- memo string
- attachments FileReference[]
- anydata...
- Fields Included from *InvoiceDetailAllOf2
- invoice_number string
- invoice_date DateNoTime
- payment_term InvoicePaymentTerm
- metadata Metadata
- anydata...
paypal.invoices: InvoiceDetailAllOf2
Fields
- invoice_number? string - The invoice number. Default is the number that is auto-incremented number from the last number.
- invoice_date? DateNoTime - The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years
- payment_term? InvoicePaymentTerm - The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days
- metadata? Metadata - The audit metadata. Captures all invoicing actions on create, send, update, and cancel
paypal.invoices: InvoiceNumber
The invoice number
Fields
- invoice_number? string - The invoice number. If you omit this value, the default is the auto-incremented number from the last number
paypal.invoices: InvoicePaymentTerm
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days
Fields
- Fields Included from *PaymentTerm
- term_type PaymentTermType
- anydata...
- Fields Included from *InvoicePaymentTermAllOf2
- due_date DateNoTime
- anydata...
paypal.invoices: InvoicePaymentTermAllOf2
Fields
- due_date? DateNoTime - The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard
date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years
paypal.invoices: InvoicerInfo
The invoicer business information that appears on the invoice
Fields
- Fields Included from *ContactNameAddress
- business_name string
- name Name
- address AddressPortable
- anydata...
- Fields Included from *InvoicerInfoAllOf2
- email_address EmailAddress
- phones PhoneDetail[]
- website string
- tax_id string
- additional_notes string
- logo_url string
- anydata...
paypal.invoices: InvoicerInfoAllOf2
Fields
- email_address? EmailAddress - The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
- phones? PhoneDetail[] - An array of invoicer's phone numbers. The invoicer can choose to hide the phone number on the invoice.
- website? string - The invoicer's website.
- tax_id? string - The invoicer's tax ID.
- additional_notes? string - Any additional information. Includes business hours.
- logo_url? string - The full URL to an external logo image. The logo image must not be larger than 250 pixels wide by 90 pixels high.
paypal.invoices: Invoices
An array of merchant invoices. Includes the total invoices count and HATEOAS links for navigation
Fields
- links? LinkDescription[] - An array of request-related HATEOAS links
- total_pages? int - The total number of pages that are available for the search criteria. <blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of total_pages is constant. The value MAY change from one request to the next</blockquote>
- total_items? int - The total number of invoices that match the search criteria.<blockquote><strong>Note:</strong> Clients MUST NOT assume that the value of <code>total_items</code> is constant. The value MAY change from one request to the next.</blockquote>
- items? Invoice[] - The list of invoices that match the search criteria
paypal.invoices: InvoicesCreateHeaders
Represents the Headers record for the operation: invoices.create
Fields
- Prefer string(default "return=representation") - Specifies the preferred response format.
paypal.invoices: InvoicesListQueries
Represents the Queries record for the operation: invoices.list
Fields
- page int(default 1) - The page number to be retrieved, for the list of templates. So, a combination of
page=1
andpage_size=20
returns the first 20 templates. A combination ofpage=2
andpage_size=20
returns the next 20 templates
- fields string(default "all") - The fields to return in the response. Value is
all
ornone
. To return only the template name, ID, and default attributes, specifynone
- total_required boolean(default false) - Indicates whether the to show <code>total_pages</code> and <code>total_items</code> in the response
- page_size int(default 20) - The maximum number of templates to return in the response
paypal.invoices: InvoicesSearchInvoicesQueries
Represents the Queries record for the operation: invoices.search-invoices
Fields
- page int(default 1) - The page number to be retrieved, for the list of templates. So, a combination of
page=1
andpage_size=20
returns the first 20 templates. A combination ofpage=2
andpage_size=20
returns the next 20 templates
- total_required boolean(default false) - Indicates whether the to show <code>total_pages</code> and <code>total_items</code> in the response
- page_size int(default 20) - The maximum number of templates to return in the response
paypal.invoices: InvoicesUpdateHeaders
Represents the Headers record for the operation: invoices.update
Fields
- Prefer string(default "return=representation") - Specifies the preferred response format.
paypal.invoices: InvoicesUpdateQueries
Represents the Queries record for the operation: invoices.update
Fields
- send_to_recipient boolean(default true) - Indicates whether to send the invoice update notification to the recipient
- send_to_invoicer boolean(default true) - Indicates whether to send the invoice update notification to the merchant
paypal.invoices: InvoicingGenerateNextInvoiceNumberHeaders
Represents the Headers record for the operation: invoicing.generate-next-invoice-number
Fields
- Content\-Type "application/json" (default "application/json") - The content type should be set to
application/json
.
paypal.invoices: Item
An array of invoice line item information. The maximum items for an invoice is 100
Fields
- quantity string - The quantity of the item that the invoicer provides to the payer. Value is from
-1000000
to1000000
. Supports up to five decimal places
- item_date? DateNoTime -
- name string - The item name for the invoice line item
- description? string - The item description for the invoice line item
- discount? Discount - The discount as a percent or amount at invoice level. The invoice discount amount is subtracted from the item total
- unit_of_measure? UnitOfMeasure -
- tax? Tax - The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total
- id? string - The ID of the invoice line item
- unit_amount Money -
paypal.invoices: LinkDescription
The request-related HATEOAS link information
Fields
- method? "GET"|"POST"|"PUT"|"DELETE"|"HEAD"|"CONNECT"|"OPTIONS"|"PATCH" - The HTTP method required to make the related call
- rel string - The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations
- href string - The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call
paypal.invoices: Metadata
The audit metadata. Captures all invoicing actions on create, send, update, and cancel
Fields
- Fields Included from *TemplateMetadata
- Fields Included from *MetadataAllOf2
paypal.invoices: MetadataAllOf2
Fields
- cancel_time? DateTime - The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
- cancelled_by? string - The actor who canceled the resource.
- first_sent_time? DateTime - The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
- last_sent_time? DateTime - The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.<blockquote><strong>Note:</strong> The regular expression provides guidance but does not reject all invalid dates.</blockquote>
- last_sent_by? string - The email address of the account that last sent the resource.
- created_by_flow? InvoiceCreationFlow - The frequency at which the invoice is sent:<ul><li>Multiple recipient. Sent to multiple recipients.</li><li>Batch. Sent in a batch.</li><li>Regular single. Sent one time to a single recipient.</li></ul>
- recipient_view_url? string - The URL for the invoice payer view hosted on paypal.com.
- invoicer_view_url? string - The URL for the invoice merchant view hosted on paypal.com.
paypal.invoices: Money
The currency and amount for a financial transaction, such as a balance or payment due
Fields
- value string - The value, which might be:<ul><li>An integer for currencies like
JPY
that are not typically fractional.</li><li>A decimal fraction for currencies likeTND
that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see Currency Codes
- currency_code CurrencyCode -
paypal.invoices: Name
The name of the party
Fields
- full_name? string - When the party is a person, the party's full name
- prefix? string - The prefix, or title, to the party's name
- surname? string - When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname
- given_name? string - When the party is a person, the party's given, or first, name
- middle_name? string - When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name
- suffix? string - The suffix for the party's name
- alternate_full_name? string - DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business
paypal.invoices: Notification
The email or SMS notification to send to the invoicer or payer on sending an invoice
Fields
- note? string - A note to the payer
- send_to_recipient boolean(default true) - Indicates whether to send a copy of the email to the recipient
- subject? string - The subject of the email that is sent as a notification to the recipient
- send_to_invoicer boolean(default false) - Indicates whether to send a copy of the email to the merchant
- additional_recipients? EmailAddress[] - An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.<blockquote><strong>Note:</strong> Valid values are email addresses in the
additional_recipients
value associated with the invoice.</blockquote>
paypal.invoices: OAuth2ClientCredentialsGrantConfig
OAuth2 Client Credentials Grant Configs
Fields
- tokenUrl string(default "https://api-m.sandbox.paypal.com/v1/oauth2/token") - Token URL
paypal.invoices: PartialPayment
The partial payment details. Includes the minimum amount that the invoicer expects from the payer
Fields
- minimum_amount_due? Money -
- allow_partial_payment boolean(default false) - Indicates whether the invoice allows a partial payment. If
false
, the invoice must be paid in full. Iftrue
, the invoice allows partial payments.<blockquote><strong>Note:</strong> This feature is not available for users inIndia
,Brazil
, orIsrael
.</blockquote>
paypal.invoices: PaymentDetail
The payment details of the invoice. Includes payment type, method, date, discount, and transaction type
Fields
- note? string - A note associated with an external cash or check payment
- shipping_info? ContactNameAddress -
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- method PaymentMethod - The payment mode or method through which the invoicer can accept the payments
- payment_id? string - The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type
- 'type? PaymentType - The payment type. Can be PayPal or an external payment. Includes cash or a check
- payment_date? DateNoTime -
paypal.invoices: PaymentReference
The reference to the payment detail
Fields
- payment_id? string - The ID for the invoice payment
paypal.invoices: Payments
An array of payments registered against the invoice
Fields
- paid_amount? Money -
- transactions? PaymentDetail[] - An array of payment details for the invoice. The payment details of the invoice like payment type, method, date, discount and transaction type
paypal.invoices: PaymentTerm
The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days
Fields
- term_type? PaymentTermType -
paypal.invoices: Phone
The phone number, in its canonical international E.164 numbering plan format
Fields
- country_code string - The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN)
- extension_number? string - The extension number
- national_number string - The national number, in its canonical international E.164 numbering plan format. The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN)
paypal.invoices: PhoneDetail
The phone details. Includes the phone number and type
Fields
- Fields Included from *Phone
- Fields Included from *PhoneDetailAllOf2
- phone_type PhoneType
- anydata...
- phone_type PhoneType -
paypal.invoices: PhoneDetailAllOf2
Fields
- phone_type? PhoneType - The phone type
paypal.invoices: QrConfig
The configuration for a QR code
Fields
- width int(default 500) - The width, in pixels, of the QR code image. Value is from
150
to500
- action string(default "pay") - The type of URL for which to generate a QR code. Valid values are
pay
anddetails
- height int(default 500) - The height, in pixels, of the QR code image. Value is from
150
to500
paypal.invoices: RecipientInfo
The billing and shipping information. Includes name, email, address, phone, and language
Fields
- shipping_info? ContactNameAddress -
- billing_info? BillingInfo -
paypal.invoices: RefundDetail
The refund details of the invoice. Includes the refund type, date, amount, and method
Fields
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- method PaymentMethod - The payment mode or method through which the invoicer can accept the payments
- 'type? PaymentType - The payment type. Can be PayPal or an external payment. Includes cash or a check
- refund_id? string - The ID for a PayPal payment transaction. Required for the
PAYPAL
payment type
- refund_date? DateNoTime -
paypal.invoices: RefundReference
The reference to the refund payment detail
Fields
- refund_id? string - The ID of the refund of an invoice payment
paypal.invoices: Refunds
The invoicing refund details. Includes the refund type, date, amount, and method
Fields
- refund_amount? Money -
- transactions? RefundDetail[] - An array of refund details for the invoice. Includes the refund type, date, amount, and method
paypal.invoices: SearchData
The invoice search parameters
Fields
- payment_date_range? DateTimeRange -
- recipient_last_name? string - Filters the search by the recipient last name
- recipient_first_name? string - Filters the search by the recipient first name
- recipient_email? string - Filters the search by the email address
- invoice_date_range? DateRange -
- memo? string - A private bookkeeping memo for the user
- currency_code? CurrencyCode -
- reference? string - The reference data, such as a PO number
- total_amount_range? AmountRange -
- archived? boolean - Indicates whether to list merchant-archived invoices in the response. Value is:<ul><li><code>true</code>. Response lists only merchant-archived invoices.</li><li><code>false</code>. Response lists only unarchived invoices.</li><li><code>null</code>. Response lists all invoices.</li></ul>
- due_date_range? DateRange -
- creation_date_range? DateTimeRange -
- recipient_business_name? string - Filters the search by the recipient business name
- fields? string[] - A CSV file of fields to return for the user, if available. Because the invoice object can be very large, field filtering is required. Valid collection fields are <code>items</code>, <code>payments</code>, <code>refunds</code>, <code>additional_recipients_info</code>, and <code>attachments</code>
- invoice_number? string - Filters the search by the invoice number
- status? InvoiceStatus[] - An array of status values
paypal.invoices: ShippingCost
The shipping fee for all items. Includes tax on shipping
Fields
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- tax? Tax - The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total
paypal.invoices: Tax
The tax information. Includes the tax name and tax rate of invoice items. The tax amount is added to the item total
Fields
- amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
- name string - The name of the tax applied on the invoice items
- percent Percentage - The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as
19.99
paypal.invoices: Template
The template with invoice details to load with all captured fields
Fields
- settings? TemplateSettings - The template settings. Sets a template as the default template or edit template
- standard_template? boolean - Indicates whether this template is a invoicer-created custom template. The system generates non-custom templates
- template_info? TemplateInfo -
- name? string - The template name.<blockquote><strong>Note:</strong> The template name must be unique.</blockquote>
- unit_of_measure? UnitOfMeasure -
- default_template? boolean - Indicates whether this template is the default template. A invoicer can have one default template
- links? LinkDescription[] - An array of request-related HATEOAS links
- id? string - The ID of the template
paypal.invoices: TemplateConfiguration
The template configuration details. Includes tax information, tip, and partial payment
Fields
- tax_calculated_after_discount boolean(default true) - Indicates whether the tax is calculated before or after a discount. If
false
, the tax is calculated before a discount. Iftrue
, the tax is calculated after a discount
- partial_payment? PartialPayment -
- allow_tip boolean(default false) - Indicates whether the invoice enables the customer to enter a tip amount during payment. If
true
, the invoice shows a tip amount field so that the customer can enter a tip amount. Iffalse
, the invoice does not show a tip amount field.<blockquote><strong>Note:</strong> This feature is not available for users inHong Kong
,Taiwan
,India
, orJapan
.</blockquote>
- tax_inclusive boolean(default false) - Indicates whether the unit price includes tax
paypal.invoices: TemplateDetail
The template-related details. Includes notes, terms and conditions, memo, and attachments
Fields
- Fields Included from *Detail
- reference string
- currency_code CurrencyCode
- note string
- terms_and_conditions string
- memo string
- attachments FileReference[]
- anydata...
- Fields Included from *TemplateDetailAllOf2
- payment_term PaymentTerm
- metadata TemplateMetadata
- anydata...
paypal.invoices: TemplateDetailAllOf2
Fields
- payment_term? PaymentTerm - The payment term of the invoice. Payment can be due upon receipt, a specified date, or in a set number of days
- metadata? TemplateMetadata - The audit metadata. Captures all template actions on create and update
paypal.invoices: TemplateDisplayPreference
The template display preference
Fields
- hidden boolean(default false) - Indicates whether to show or hide this field
paypal.invoices: TemplateInfo
The template details. Includes invoicer business information, invoice recipients, items, and configuration
Fields
- amount? AmountSummaryDetail - The invoice amount summary of item total, discount, tax total, and shipping
- due_amount? Money -
- configuration? TemplateConfiguration - The template configuration details. Includes tax information, tip, and partial payment
- invoicer? InvoicerInfo - The invoicer business information that appears on the invoice
- detail? TemplateDetail - The template-related details. Includes notes, terms and conditions, memo, and attachments
- primary_recipients? RecipientInfo[] - The billing and shipping information. Includes name, email, address, phone, and language
- additional_recipients? EmailAddress[] - An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.<blockquote><strong>Note:</strong> Valid values are email addresses in the
additional_recipients
value associated with the invoice.</blockquote>
- items? Item[] - An array of invoice line-item information
paypal.invoices: TemplateItemSetting
The template item setting. Sets a template as the default template or edit template
Fields
- display_preference? TemplateDisplayPreference -
- field_name? TemplateItemField -
paypal.invoices: TemplateMetadata
The audit metadata. Captures all template actions on create and update
Fields
- last_update_time? DateTime -
- last_updated_by? string - The email address of the account that last edited the resource
- create_time? DateTime -
- created_by? string - The email address of the account that created the resource
paypal.invoices: Templates
An array of merchant-created templates with associated details that include the emails, addresses, and phone numbers from the user's PayPal profile
Fields
- emails? EmailAddress - The internationalized email address.<blockquote><strong>Note:</strong> Up to 64 characters are allowed before and 255 characters are allowed after the <code>@</code> sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted <code>@</code> sign exists.</blockquote>
- addresses? AddressPortable[] - An array of addresses in the user's PayPal profile
- templates? Template[] - An array of details for each template. If
fields
isnone
, returns only the template name, ID, and default status
- phones? PhoneDetail[] - An array of phone numbers in the user's PayPal profile
- links? LinkDescription[] - An array of request-related HATEOAS links
paypal.invoices: TemplateSettings
The template settings. Sets a template as the default template or edit template
Fields
- template_item_settings? TemplateItemSetting[] - The template item headers display preference
- template_subtotal_settings? TemplateSubtotalSetting[] - The template subtotal headers display preference
paypal.invoices: TemplatesListQueries
Represents the Queries record for the operation: templates.list
Fields
- page int(default 1) - The page number to be retrieved, for the list of templates. So, a combination of
page=1
andpage_size=20
returns the first 20 templates. A combination ofpage=2
andpage_size=20
returns the next 20 templates
- fields string(default "all") - The fields to return in the response. Value is
all
ornone
. To return only the template name, ID, and default attributes, specifynone
- page_size int(default 20) - The maximum number of templates to return in the response
paypal.invoices: TemplateSubtotalSetting
The template subtotal setting. Includes the field name and display preference
Fields
- display_preference? TemplateDisplayPreference -
- field_name? TemplateSubtotalField -
Union types
paypal.invoices: UnitOfMeasure
UnitOfMeasure
The unit of measure for the invoiced item
paypal.invoices: PaymentTermType
PaymentTermType
The payment term. Payment can be due upon receipt, a specified date, or in a set number of days
paypal.invoices: PhoneType
PhoneType
The phone type
paypal.invoices: PaymentMethod
PaymentMethod
The payment mode or method through which the invoicer can accept the payments
paypal.invoices: InvoiceCreationFlow
InvoiceCreationFlow
The frequency at which the invoice is sent:
- Multiple recipient. Sent to multiple recipients.
- Batch. Sent in a batch.
- Regular single. Sent one time to a single recipient.
paypal.invoices: TemplateSubtotalField
TemplateSubtotalField
The field names in the template for discount, shipping, and custom amounts
paypal.invoices: PaymentType
PaymentType
The payment type. Can be PayPal or an external payment. Includes cash or a check
paypal.invoices: TemplateItemField
TemplateItemField
The field names for the invoice line items in the template
paypal.invoices: InvoiceStatus
InvoiceStatus
The status of the invoice
String types
paypal.invoices: DateTime
DateTime
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
paypal.invoices: CurrencyCode
CurrencyCode
The three-character ISO-4217 currency code that identifies the currency
paypal.invoices: EmailAddress
EmailAddress
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the@
sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@
sign exists.
paypal.invoices: DateNoTime
DateNoTime
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years
paypal.invoices: Language
Language
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code
paypal.invoices: CountryCode
CountryCode
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain isGB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
paypal.invoices: Percentage
Percentage
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99
Import
import ballerinax/paypal.invoices;
Other versions
1.0.0
Metadata
Released date: 28 days ago
Version: 1.0.0
License: Apache-2.0
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 1
Current verison: 1
Weekly downloads
Keywords
PayPal
Invoicing
Contributors