Ballerina library

paypal.payments

Module paypal.payments

OverviewSetup guideQuickstartExamples

API

Client

Definitions

ActivityTimestamps
Authorization
Authorization2
Authorization2AllOf2
AuthorizationAllOf2
AuthorizationsCaptureHeaders
AuthorizationsReauthorizeHeaders
AuthorizationStatus
AuthorizationStatusDetails
AuthorizationsVoidHeaders
Capture
Capture2
Capture2AllOf2
CaptureAllOf2
CaptureRequest
CaptureRequestAllOf2
CapturesRefundHeaders
CaptureStatus
CaptureStatusDetails
ConnectionConfig
ExchangeRate
LinkDescription
MerchantPayableBreakdown
Money
NetAmountBreakdownItem
NetworkTransactionReference
OAuth2ClientCredentialsGrantConfig
PayeeBase
PaymentInstruction
PaymentInstruction2
PlatformFee
ProcessorResponse
ReauthorizeRequest
Refund
RefundAllOf2
RefundRequest
RefundStatus
RefundStatusDetails
RelatedIds
SellerProtection
SellerReceivableBreakdown
SupplementaryData
SupplementaryPurchaseData

CardBrand
DisbursementMode

Email
AccountId
DateTime
CurrencyCode

ballerinax/paypal.payments Ballerina library

2.0.0

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.payments package provides a Ballerina connector for interacting with the PayPal Payments API v2, allowing you to authorize payments, capture authorized payments, refund captured payments, void authorizations, and reauthorize expired authorizations in your Ballerina applications.

Setup guide

To use the PayPal Payments connector, you must have access to a PayPal Developer account.

Step 1: Create a business account

  1. Open the PayPal Developer Dashboard.

  2. Click on "Sandbox Accounts" under "Testing Tools".

    Sandbox accounts

  3. Create a Business account

    Note: Some PayPal options and features may vary by region or country; check availability before creating an account.

    Create business account

Step 2: Create a REST API app

  1. 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.

    Create app

Step 3: Obtain Client ID and Client Secret

  1. After creating your new app, you will see your Client ID and Client Secret. Make sure to copy and securely store these credentials.

    Credentials

Quickstart

To use the paypal.payments connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Import the paypal.payments module.

Copy
import ballerinax/paypal.payments as paypal;

Step 2: Instantiate a new connector

  1. Create a Config.toml file and configure the obtained credentials in the above steps as follows:
Copy
clientId = "<test-client-id>"
clientSecret = "<test-client-secret>"
  1. Create a paypal:ConnectionConfig with the obtained credentials and initialize the connector with it.
Copy
configurable string clientId = ?;
configurable string clientSecret= ?;
Copy
final paypal:Client paypal = check new ({
    auth: {
        clientId,
        clientSecret
    }
}, serviceUrl);

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Capture an authorized payment

Copy
public function main() returns error? {
    paypal:CaptureRequest captureRequest = {
        amount: {
            currency_code: "USD",
            value: "100.00"
        },
        final_capture: true
    };
    
    paypal:Capture2 response = check paypal->/authorizations/[authorizationId]/capture.post(captureRequest);
}

Step 4: Run the Ballerina application

Copy
bal run

Examples

The PayPal Payments connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

  1. Order creation: Process a complete product purchase from order creation through payment authorization, capture, and partial refunds.

  2. Subscription management: Simulate a recurring billing flow with subscription-style orders, monthly payments, plan switching, and pro-rated refunds.

Clients

paypal.payments: Client

Isolated

Call the Payments API to authorize payments, capture authorized payments, refund payments that have already been captured, and show payment information. Use the Payments API in conjunction with the Orders API. For more information, see the PayPal Checkout Overview.

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/payments" - URL of the target service

get authorizations/[string authorizationId]

Isolated FunctionResource Function
function get authorizations/[string authorizationId](map<string|string[]> headers) returns Authorization2|error

Show details for authorized payment

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type
  • Authorization2|error - A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details

post authorizations/[string authorizationId]/capture

Isolated FunctionResource Function
function post authorizations/[string authorizationId]/capture(CaptureRequest payload, AuthorizationsCaptureHeaders headers) returns Capture2|error

Capture authorized payment

Parameters
Return Type
  • Capture2|error - A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows captured payment details

post authorizations/[string authorizationId]/reauthorize

Isolated FunctionResource Function
function post authorizations/[string authorizationId]/reauthorize(ReauthorizeRequest payload, AuthorizationsReauthorizeHeaders headers) returns Authorization2|error

Reauthorize authorized payment

Parameters
Return Type
  • Authorization2|error - A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows the reauthorized payment details

post authorizations/[string authorizationId]/void

Isolated FunctionResource Function
function post authorizations/[string authorizationId]/void(AuthorizationsVoidHeaders headers) returns Authorization2|error?

Void authorized payment

Parameters
Return Type
  • Authorization2|error? - A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows authorization details. This response is returned when the Prefer header is set to return=representation

get captures/[string captureId]

Isolated FunctionResource Function
function get captures/[string captureId](map<string|string[]> headers) returns Capture2|error

Show captured payment details

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type
  • Capture2|error - A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows captured payment details

post captures/[string captureId]/refund

Isolated FunctionResource Function
function post captures/[string captureId]/refund(RefundRequest payload, CapturesRefundHeaders headers) returns Refund|error

Refund captured payment

Parameters
Return Type
  • Refund|error - A successful request returns the HTTP <code>201 Created</code> status code and a JSON response body that shows refund details

get refunds/[string refundId]

Isolated FunctionResource Function
function get refunds/[string refundId](map<string|string[]> headers) returns Refund|error

Show refund details

Parameters
  • headers map<string|string[]> (default {}) - Headers to be sent with the request
Return Type
  • Refund|error - A successful request returns the HTTP <code>200 OK</code> status code and a JSON response body that shows refund details

Records

paypal.payments: ActivityTimestamps

The date and time stamps that are common to authorized payment, captured payment, and refund transactions

Fields

paypal.payments: Authorization

The authorized payment transaction

Fields

paypal.payments: Authorization2

The authorized payment transaction

Fields

paypal.payments: Authorization2AllOf2

Fields
  • payee? PayeeBase - The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee

paypal.payments: AuthorizationAllOf2

Fields
  • id? string - The PayPal-generated ID for the authorized payment.
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
  • custom_id? string - The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.
  • expiration_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>

paypal.payments: AuthorizationsCaptureHeaders

Represents the Headers record for the operation: authorizations.capture

Fields
  • PayPal\-Request\-Id? string - The server stores keys for 45 days
  • Prefer string(default "return=minimal") - The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>

paypal.payments: AuthorizationsReauthorizeHeaders

Represents the Headers record for the operation: authorizations.reauthorize

Fields
  • PayPal\-Request\-Id? string - The server stores keys for 45 days
  • Prefer string(default "return=minimal") - The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>

paypal.payments: AuthorizationStatus

The status fields for an authorized payment

Fields
  • status? "CREATED"|"CAPTURED"|"DENIED"|"PARTIALLY_CAPTURED"|"VOIDED"|"PENDING" - The status for the authorized payment

paypal.payments: AuthorizationStatusDetails

The details of the authorized payment status

Fields
  • reason? "PENDING_REVIEW" - The reason why the authorized status is PENDING

paypal.payments: AuthorizationsVoidHeaders

Represents the Headers record for the operation: authorizations.void

Fields
  • PayPal\-Auth\-Assertion? string - An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.<blockquote><strong>Note:</strong>For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.</blockquote>
  • Prefer string(default "return=minimal") - The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>

paypal.payments: Capture

A captured payment

Fields
  • status_details CaptureStatusDetails
  • status "COMPLETED"|"DECLINED"|"PARTIALLY_REFUNDED"|"PENDING"|"REFUNDED"|"FAILED"
  • anydata...

paypal.payments: Capture2

A captured payment

Fields

paypal.payments: Capture2AllOf2

Fields
  • payee? PayeeBase - The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee

paypal.payments: CaptureAllOf2

Fields
  • id? string - The PayPal-generated ID for the captured payment.
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
  • custom_id? string - The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.
  • final_capture boolean(default false) - Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.
  • seller_receivable_breakdown? SellerReceivableBreakdown - The detailed breakdown of the capture activity. This is not available for transactions that are in pending state
  • disbursement_mode? DisbursementMode - The funds that are held on behalf of the merchant
  • processor_response? ProcessorResponse - The processor response information for payment requests, such as direct credit card transactions

paypal.payments: CaptureRequest

Captures either a portion or the full authorized amount of an authorized payment

Fields
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives
  • note_to_payer? string - An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives

paypal.payments: CaptureRequestAllOf2

Fields
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
  • final_capture boolean(default false) - Indicates whether you can make additional captures against the authorized payment. Set to true if you do not intend to capture additional payments against the authorization. Set to false if you intend to capture additional payments against the authorization.
  • payment_instruction? PaymentInstruction - Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order
  • note_to_payer? string - An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives.
  • soft_descriptor? string - The payment descriptor on the payer's account statement.

paypal.payments: CapturesRefundHeaders

Represents the Headers record for the operation: captures.refund

Fields
  • PayPal\-Request\-Id? string - The server stores keys for 45 days
  • PayPal\-Auth\-Assertion? string - An API-caller-provided JSON Web Token (JWT) assertion that identifies the merchant. For details, see PayPal-Auth-Assertion.<blockquote><strong>Note:</strong>For three party transactions in which a partner is managing the API calls on behalf of a merchant, the partner must identify the merchant using either a PayPal-Auth-Assertion header or an access token with target_subject.</blockquote>
  • Prefer string(default "return=minimal") - The preferred server response upon successful completion of the request. Value is:<ul><li><code>return=minimal</code>. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the <code>id</code>, <code>status</code> and HATEOAS links.</li><li><code>return=representation</code>. The server returns a complete resource representation, including the current state of the resource.</li></ul>

paypal.payments: CaptureStatus

The status of a captured payment

Fields
  • status? "COMPLETED"|"DECLINED"|"PARTIALLY_REFUNDED"|"PENDING"|"REFUNDED"|"FAILED" - The status of the captured payment

paypal.payments: CaptureStatusDetails

The details of the captured payment status

Fields
  • reason? "BUYER_COMPLAINT"|"CHARGEBACK"|"ECHECK"|"INTERNATIONAL_WITHDRAWAL"|"OTHER"|"PENDING_REVIEW"|"RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION"|"REFUNDED"|"TRANSACTION_APPROVED_AWAITING_FUNDING"|"UNILATERAL"|"VERIFICATION_REQUIRED" - The reason why the captured payment status is PENDING or DENIED

paypal.payments: ConnectionConfig

Closed record

Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Fields
  • 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 as nilable types. Enabled by default.

paypal.payments: ExchangeRate

The exchange rate that determines the amount to convert from one currency to another currency

Fields
  • value? string - The target currency amount. Equivalent to one unit of the source currency. Formatted as integer or decimal value with one to 15 digits to the right of the decimal point

paypal.payments: 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
  • 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. The href is the key HATEOAS component that links a completed call with a subsequent call

paypal.payments: MerchantPayableBreakdown

The breakdown of the refund

Fields
  • platform_fees? PlatformFee[] - An array of platform or partner fees, commissions, or brokerage fees for the refund
  • net_amount_in_receivable_currency? Money -
  • total_refunded_amount? Money -
  • paypal_fee_in_receivable_currency? Money -
  • net_amount_breakdown? NetAmountBreakdownItem[] - An array of breakdown values for the net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the payee holds their funds

paypal.payments: 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 like TND that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see Currency Codes

paypal.payments: NetAmountBreakdownItem

The net amount. Returned when the currency of the refund is different from the currency of the PayPal account where the merchant holds their funds

Fields
  • converted_amount? Money -

paypal.payments: NetworkTransactionReference

Reference values used by the card network to identify a transaction

Fields
  • date? string - The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date
  • acquirer_reference_number? string - Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks
  • id string - Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -
  • network? CardBrand - The card network or brand. Applies to credit, debit, gift, and payment cards

paypal.payments: OAuth2ClientCredentialsGrantConfig

Closed record

OAuth2 Client Credentials Grant Configs

Fields
  • tokenUrl string(default "https://api.sandbox.paypal.com/v1/oauth2/token") - Token URL

paypal.payments: PayeeBase

The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee

Fields

paypal.payments: PaymentInstruction

Any additional payment instructions to be consider during payment processing. This processing instruction is applicable for Capturing an order or Authorizing an Order

Fields
  • platform_fees? PlatformFee[] - An array of various fees, commissions, tips, or donations. This field is only applicable to merchants that been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability
  • payee_receivable_fx_rate_id? string - FX identifier generated returned by PayPal to be used for payment processing in order to honor FX rate (for eligible integrations) to be used when amount is settled/received into the payee account
  • payee_pricing_tier_id? string - This field is only enabled for selected merchants/partners to use and provides the ability to trigger a specific pricing rate/plan for a payment transaction. The list of eligible 'payee_pricing_tier_id' would be provided to you by your Account Manager. Specifying values other than the one provided to you by your account manager would result in an error

paypal.payments: PaymentInstruction2

Any additional payments instructions during refund payment processing. This object is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability

Fields
  • platform_fees? PlatformFee[] - Specifies the amount that the API caller will contribute to the refund being processed. The amount needs to be lower than platform_fees amount originally captured or the amount that is remaining if multiple refunds have been processed. This field is only applicable to merchants that have been enabled for PayPal Commerce Platform for Marketplaces and Platforms capability. Please speak to your account manager if you want to use this capability

paypal.payments: PlatformFee

The platform or partner fee, commission, or brokerage fee that is associated with the transaction. Not a separate or isolated transaction leg from the external perspective. The platform fee is limited in scope and is always associated with the original payment for the purchase unit

Fields
  • payee? PayeeBase - The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee
  • amount Money - The currency and amount for a financial transaction, such as a balance or payment due

paypal.payments: ProcessorResponse

The processor response information for payment requests, such as direct credit card transactions

Fields
  • cvv_code? "E"|"I"|"M"|"N"|"P"|"S"|"U"|"X"|"All others"|"0"|"1"|"2"|"3"|"4" - The card verification value code for for Visa, Discover, Mastercard, or American Express
  • response_code? "0000"|"00N7"|"0100"|"0390"|"0500"|"0580"|"0800"|"0880"|"0890"|"0960"|"0R00"|"1000"|"10BR"|"1300"|"1310"|"1312"|"1317"|"1320"|"1330"|"1335"|"1340"|"1350"|"1352"|"1360"|"1370"|"1380"|"1382"|"1384"|"1390"|"1393"|"5100"|"5110"|"5120"|"5130"|"5135"|"5140"|"5150"|"5160"|"5170"|"5180"|"5190"|"5200"|"5210"|"5400"|"5500"|"5650"|"5700"|"5710"|"5800"|"5900"|"5910"|"5920"|"5930"|"5950"|"6300"|"7600"|"7700"|"7710"|"7800"|"7900"|"8000"|"8010"|"8020"|"8030"|"8100"|"8110"|"8220"|"9100"|"9500"|"9510"|"9520"|"9530"|"9540"|"9600"|"PCNR"|"PCVV"|"PP06"|"PPRN"|"PPAD"|"PPAB"|"PPAE"|"PPAG"|"PPAI"|"PPAR"|"PPAU"|"PPAV"|"PPAX"|"PPBG"|"PPC2"|"PPCE"|"PPCO"|"PPCR"|"PPCT"|"PPCU"|"PPD3"|"PPDC"|"PPDI"|"PPDV"|"PPDT"|"PPEF"|"PPEL"|"PPER"|"PPEX"|"PPFE"|"PPFI"|"PPFR"|"PPFV"|"PPGR"|"PPH1"|"PPIF"|"PPII"|"PPIM"|"PPIT"|"PPLR"|"PPLS"|"PPMB"|"PPMC"|"PPMD"|"PPNC"|"PPNL"|"PPNM"|"PPNT"|"PPPH"|"PPPI"|"PPPM"|"PPQC"|"PPRE"|"PPRF"|"PPRR"|"PPS0"|"PPS1"|"PPS2"|"PPS3"|"PPS4"|"PPS5"|"PPS6"|"PPSC"|"PPSD"|"PPSE"|"PPTE"|"PPTF"|"PPTI"|"PPTR"|"PPTT"|"PPTV"|"PPUA"|"PPUC"|"PPUE"|"PPUI"|"PPUP"|"PPUR"|"PPVC"|"PPVE"|"PPVT" - Processor response code for the non-PayPal payment processor errors
  • payment_advice_code? "01"|"02"|"03"|"21" - The declined payment transactions might have payment advice codes. The card networks, like Visa and Mastercard, return payment advice codes
  • avs_code? "A"|"B"|"C"|"D"|"E"|"F"|"G"|"I"|"M"|"N"|"P"|"R"|"S"|"U"|"W"|"X"|"Y"|"Z"|"Null"|"0"|"1"|"2"|"3"|"4" - The address verification code for Visa, Discover, Mastercard, or American Express transactions

paypal.payments: ReauthorizeRequest

Reauthorizes an authorized PayPal account payment, by ID. To ensure that funds are still available, reauthorize a payment after its initial three-day honor period expires. You can reauthorize a payment only once from days four to 29.

If 30 days have transpired since the date of the original authorization, you must create an authorized payment instead of reauthorizing the original authorized payment.

A reauthorized payment itself has a new honor period of three days.

You can reauthorize an authorized payment once. The allowed amount depends on context and geography, for example in US it is up to 115% of the original authorized amount, not to exceed an increase of $75 USD.

Supports only the amount request parameter.

Note: This request is currently not supported for Partner use cases.

Fields
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due

paypal.payments: Refund

The refund information

Fields

paypal.payments: RefundAllOf2

Fields
  • id? string - The PayPal-generated ID for the refund.
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives.
  • custom_id? string - The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports.
  • acquirer_reference_number? string - Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.
  • note_to_payer? string - The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives.
  • payer? PayeeBase - The details for the merchant who receives the funds and fulfills the order. The merchant is also known as the payee

paypal.payments: RefundRequest

Refunds a captured payment, by ID. For a full refund, include an empty request body. For a partial refund, include an amount object in the request body

Fields
  • amount? Money - The currency and amount for a financial transaction, such as a balance or payment due
  • custom_id? string - The API caller-provided external ID. Used to reconcile API caller-initiated transactions with PayPal transactions. Appears in transaction and settlement reports. The pattern is defined by an external party and supports Unicode
  • invoice_id? string - The API caller-provided external invoice ID for this order. The pattern is defined by an external party and supports Unicode
  • note_to_payer? string - The reason for the refund. Appears in both the payer's transaction history and the emails that the payer receives. The pattern is defined by an external party and supports Unicode

paypal.payments: RefundStatus

The refund status

Fields
  • status? "CANCELLED"|"FAILED"|"PENDING"|"COMPLETED" - The status of the refund

paypal.payments: RefundStatusDetails

The details of the refund status

Fields
  • reason? "ECHECK" - The reason why the refund has the PENDING or FAILED status

paypal.payments: RelatedIds

Identifiers related to a specific resource

Fields
  • authorization_id? string - Authorization ID related to the resource
  • capture_id? string - Capture ID related to the resource
  • order_id? string - Order ID related to the resource

paypal.payments: SellerProtection

The level of protection offered as defined by PayPal Seller Protection for Merchants

Fields
  • dispute_categories? ("ITEM_NOT_RECEIVED"|"UNAUTHORIZED_TRANSACTION")[] - An array of conditions that are covered for the transaction

paypal.payments: SellerReceivableBreakdown

The detailed breakdown of the capture activity. This is not available for transactions that are in pending state

Fields
  • platform_fees? PlatformFee[] - An array of platform or partner fees, commissions, or brokerage fees that associated with the captured payment
  • paypal_fee_in_receivable_currency? Money -
  • receivable_amount? Money -

paypal.payments: SupplementaryData

The supplementary data

Fields

paypal.payments: SupplementaryPurchaseData

The capture identification-related fields. Includes the invoice ID, custom ID, note to payer, and soft descriptor

Fields
  • invoice_id? string - The API caller-provided external invoice number for this order. Appears in both the payer's transaction history and the emails that the payer receives
  • note_to_payer? string - An informational note about this settlement. Appears in both the payer's transaction history and the emails that the payer receives

Union types

paypal.payments: CardBrand

"VISA"|"MASTERCARD"|"DISCOVER"|"AMEX"|"SOLO"|"JCB"|"STAR"|"DELTA"|"SWITCH"|"MAESTRO"|"CB_NATIONALE"|"CONFIGOGA"|"CONFIDIS"|"ELECTRON"|"CETELEM"|"CHINA_UNION_PAY"

CardBrand

The card network or brand. Applies to credit, debit, gift, and payment cards

paypal.payments: DisbursementMode

"INSTANT"|"DELAYED"

DisbursementMode

The funds that are held on behalf of the merchant

String types

paypal.payments: Email

string

Email

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.payments: AccountId

string

AccountId

The account identifier for a PayPal account

paypal.payments: DateTime

string

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.payments: CurrencyCode

string

CurrencyCode

The three-character ISO-4217 currency code that identifies the currency

Import

import ballerinax/paypal.payments;Copy

Metadata

Released date: 5 days ago

Version: 2.0.0

License: Apache-2.0

Compatibility

Platform: any

Ballerina version: 2201.12.7

GraalVM compatible: Yes

Pull count

Total: 7

Current verison: 0

Weekly downloads

Source repository

Keywords

Paypal

Payments

Contributors

Other versions

2.0.0

1.5.11.5.01.4.01.2.0
See more...

Dependencies

ballerina/url/2.6.0ballerina/time/2.7.0ballerina/constraint/1.7.0
See more...

Terms of service

Privacy policy

Cookie policy

Delete policy

© 2025 WSO2 LLC