Currency Exchange (2)

The exchange currency API to convert one currency to another one.

Important:
1. The FX rates provided are not rate guaranteed. Rate calculated at the time of transaction may be different.
2. The base exchange rate is based on rates within the wholesale currency markets on the conversion day or the prior Business Day, or, if required by law or regulation, set at the relevant government reference rate(s).
3. Additional Fee may apply.

Exchange currency detail for a single currency pair

post/v2/pricing/exchange-currency

This API provide exchange rates for a specified currency pair and enable currency conversion by computing the equivalent value in the target currency. The API provides FX rates for various scenarios, including buyer-side currency conversion, seller-side currency conversion, and remittances.

SecurityOauth2
Request
header Parameters
X-PAYPAL-SECURITY-CONTEXT
string non-empty

The Application Context object containing permissions and application claims. The object is signed by Keymaker.

Request Body schema:
conversion_reason
required
string [ 4 .. 1000 ] characters ^[A-Z_]+$

The reason for the currency exchange conversion.

Enum Value Description
WITHDRAW

Currency conversion is for withdrawing money out of PayPal to the linked bank account or eligible debit cards. Ex: If an account holds 10USD and initiates a local bank withdrawal, the 10USD will be first converted to Polish Zloty and then withdrawn to the local bank

FX_ON_SENDER

Currency Conversion is for purchasing goods/services. Ex: Buyer is using instrument in a different currency to fund the transaction.

FX_ON_RECEIVER

Currency Conversion is for Receiving funds. Ex: Merchant is receiving funds in a different currency than the transaction currency.

FX_ON_EXISTING_RATE

Currency conversion is on the previous rate used Ex: The rate used is in the audit trail, if client want to use already known exchange rate.

FX_ON_BALANCE_TRANSFER

Currency Conversion is for Balance transfer. Ex: Customer converting money from one holding currency to another.

NON_TRANSACTION_FX

Used when fetching rates for purposes other than transactions.

MARKET_RATE_FX

Use customer rate for conversion without fee.

trade_type
required
string [ 3 .. 1000 ] characters ^[A-Z_]+$

The type of the currency exchange.

Enum Value Description
BUY

When you intent to buy amount specified in the request with the currency mentioned in target currency code.

SELL

When you intent to sell the amount specified in the request and receive amount in target currency.This is default trade type.

fx_id
string [ 1 .. 4000 ] characters ^[ -~]+$

A previous reference can be passed in to get a rate quote amount based on a previous rate.

required
object (Money)

The from amount for currency exchange.

target_currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The target currency code.

object (Object for exchange currency pricing details.)

Deprecated. Use price_category and legal_country_code under user_profile.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows exchange currency details.

400

Request is not well-formed, syntactically incorrect, or violates schema.

500

An internal server error has occurred.

Request samples
{
  • "amount": {
    • "currency_code": "USD",
    • "value": "160"
    },
  • "target_currency_code": "AUD",
  • "conversion_reason": "NON_TRANSACTION_FX",
  • "trade_type": "BUY"
}
Response samples
application/json
{
  • "source_amount": {
    • "currency_code": "AUD",
    • "value": "252.39"
    },
  • "target_amount": {
    • "currency_code": "USD",
    • "value": "160.00"
    },
  • "source_usd_amount": {
    • "currency_code": "USD",
    • "value": "160.00"
    },
  • "target_usd_amount": {
    • "currency_code": "USD",
    • "value": "160.00"
    },
  • "exchange_rate": "0.633943370963921",
  • "reference_id": "V:1:AUD:25239:USD:16000:0.63394337096392100000;C:0:M:USD;O:10723376:1.5723370440:1.5774279625:1.5825188811;E:rr:0.6339433709639213;",
  • "effective_time": "2025-02-26T08:46:13Z"
}

Exchange currency detail for a multiple currency pair

post/v2/pricing/exchange-currencies

This API provides exchange rates for multiple currency pairs in a single request, enabling efficient bulk currency conversion. It calculates the equivalent values in target currencies based on provided base amounts and applies real-time FX rates. Supporting various use cases, including buyer-side and seller-side conversions, remittances, and large-scale financial transactions.

SecurityOauth2
Request
header Parameters
X-PAYPAL-SECURITY-CONTEXT
string non-empty

The Application Context object containing permissions and application claims. The object is signed by Keymaker.

Request Body schema:
required
Array of objects (Exchange currency request.) [ 1 .. 20 ] items

List of exchange currency request. The requests would be processed sequentially.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows exchange currency details.

400

Request is not well-formed, syntactically incorrect, or violates schema.

500

An internal server error has occurred.

Request samples
{
  • "exchange_currency_requests": [
    • {
      • "bulk_id": "123123001",
      • "amount": {
        • "currency_code": "USD",
        • "value": "160"
        },
      • "target_currency_code": "AUD",
      • "conversion_reason": "NON_TRANSACTION_FX",
      • "trade_type": "BUY"
      },
    • {
      • "bulk_id": "123123002",
      • "amount": {
        • "currency_code": "USD",
        • "value": "160"
        },
      • "target_currency_code": "EUR",
      • "conversion_reason": "NON_TRANSACTION_FX",
      • "trade_type": "BUY"
      }
    ]
}
Response samples
application/json
{
  • "exchange_currency_responses": [
    • {
      • "bulk_id": "123123001",
      • "source_amount": {
        • "currency_code": "AUD",
        • "value": "252.39"
        },
      • "target_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "source_usd_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "target_usd_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "exchange_rate": "0.633943370963921",
      • "reference_id": "V:1:AUD:25239:USD:16000:0.63394337096392100000;C:0:M:USD;O:10723376:1.5723370440:1.5774279625:1.5825188811;E:rr:0.6339433709639213;",
      • "effective_time": "2025-02-26T08:46:13Z"
      },
    • {
      • "bulk_id": "123123002",
      • "source_amount": {
        • "currency_code": "EUR",
        • "value": "152.56"
        },
      • "target_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "source_usd_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "target_usd_amount": {
        • "currency_code": "USD",
        • "value": "160.00"
        },
      • "exchange_rate": "1.048739928509471",
      • "reference_id": "V:1:EUR:15256:USD:16000:1.04873992850947100000;C:0:M:USD;O:10723423:0.9505803422:0.9535252476:0.9564701530;E:rr:1.0487399285094714;",
      • "effective_time": "2025-02-26T08:46:13Z"
      }
    ]
}

Create Exchange Rate Quote

post/v2/pricing/quote-exchange-rates

This API generates exchange rate quotes for multi-currency presentment, allowing businesses to display prices in different currencies. It facilitates currency conversion by evaluating the quoted amount based on a provided base amount.
For more information, see FX As A Service documentation.

Important: Currently this API is available only on SANDBOX.

SecurityOauth2
Request
Request Body schema:
organization
string [ 2 .. 100 ] characters ^\w{2,20}(\/\w{2,20})*$

Organization this managed account belongs to, in the partner's hierarchy, in the form of a path.

required
Array of objects (Request Object for exchange_rate_quote.) [ 1 .. 250 ] items

The details necessary to request an exchange rate. The possible details (parameters) you can specify/pass in the quote_items array are: base_currency, base_amount, quote_currency, markup_percent and fx_id.

two_way_quote
boolean

Indicator to fetch both sell and buy quotes for base or quote currency pair.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows quote exchange rate details.

400

Request is not well-formed, syntactically incorrect, or violates schema.

403

The authorization failed due to insufficient permissions.

500

An internal server error has occurred.

Request samples
{
  • "quote_items": [
    • {
      • "base_currency": "USD",
      • "base_amount": "16.80",
      • "quote_currency": "GBP"
      }
    ]
}
Response samples
application/json
{
  • "exchange_rate_quotes": [
    • {
      • "base_amount": {
        • "currency_code": "USD",
        • "value": "16.80"
        },
      • "quote_amount": {
        • "currency_code": "GBP",
        • "value": "13.69"
        },
      • "exchange_rate": "0.81477512359",
      • "fx_id": "MTFFRi1GM0RELTQyRDBCMkJELUIzNjgtNEJCMkEyRDM1OTBE",
      • "expiry_time": "2025-02-27T02:00Z",
      • "rate_refresh_time": "2025-02-27T01:00Z"
      }
    ]
}

Definitions

Address

A postal address at which the user can be contacted.

address_line_1
string <= 300 characters

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.

address_line_2
string <= 300 characters

The second line of the address. For example, suite or apartment number.

address_line_3
string <= 100 characters

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.

admin_area_4
string <= 100 characters

The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:

  • The postal sorting code for Guernsey and many French territories, such as French Guiana.
  • The fine-grained administrative levels in China.

admin_area_3
string <= 100 characters

A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:

  • Brazil. Suburb, bairro, or neighborhood.
  • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

admin_area_2
string <= 120 characters

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1
string <= 300 characters

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 not California. Value, by country, is:

  • UK. A county.
  • US. A state.
  • Canada. A province.
  • Japan. A prefecture.
  • Switzerland. A kanton.

postal_code
string <= 60 characters

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_code
required
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

object (Address Details)

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.

id
string [ 1 .. 20 ] characters

Unique identifier for this address for this user.

addressee_name
string [ 1 .. 300 ] characters

The name that should go on the mailing label with the address. For use in specifying a recipient that is not the user, required on shipping addresses.

address_confirmation_status
string

The confirmation status of the postal address.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "address_line_3": "string",
  • "admin_area_4": "string",
  • "admin_area_3": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st",
  • "address_details": {
    • "street_number": "string",
    • "street_name": "string",
    • "street_type": "string",
    • "delivery_service": "string",
    • "building_name": "string",
    • "sub_building": "string"
    },
  • "id": "string",
  • "addressee_name": "string",
  • "address_confirmation_status": "string"
}

Balance account type

The specific type of the balance account.

string (Balance account type) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The specific type of the balance account.

Enum Value Description
STANDARD_BALANCE_ACCOUNT

Standard balance account.

STANDARD_GOAL_ACCOUNT

Standard goal account.

STANDARD_SAVINGS_ACCOUNT

Standard savings account.

"STANDARD_BALANCE_ACCOUNT"

Business Contact Information

This is the placeholder to represent all the business related contact information. There could be several types of business contacts. for eg: location, shipping, billing. Billing and Shipping can be same as primary location as well, in those cases there is no need to define shipping and billing separately.

contact_type
string [ 1 .. 50 ] characters ^[0-9A-Z_]+$

The type of contact information of merchant.

Enum Value Description
SHIPPING_LOCATION

The contact type shipping is the address that the merchant use to ship the goods or receive the good.

BILLING_LOCATION

The contact type billing is the address that will be used by PayPal Inc. parties to send the billing documents for the services that PayPal provided to this merchant.

object (Address)

Business address of type of contact_type.

email_address
string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

The email provided by the party for the payment.

object (Phone info)

The merchant-provided phone associated to contact_type.

{
  • "contact_type": "SHIPPING_LOCATION",
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "address_line_3": "string",
    • "admin_area_4": "string",
    • "admin_area_3": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st",
    • "address_details": {
      • "street_number": "string",
      • "street_name": "string",
      • "street_type": "string",
      • "delivery_service": "string",
      • "building_name": "string",
      • "sub_building": "string"
      },
    • "id": "string",
    • "addressee_name": "string",
    • "address_confirmation_status": "string"
    },
  • "email_address": "string",
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "country_code": "str",
      • "national_number": "string",
      • "extension_number": "string"
      }
    }
}

Capability

The financial instrument (FI) capabilities.

name
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Capability name.

Enum Value Description
INSTALLMENT

Indicates if instrument is installment capable.

PINLESS_DEBIT

Capability indicates if instrument is Pinless Debit capable.

CAPTURE

Capability indicates if instrument is Capture capable.

TOKEN

Capability indicates if instrument is TOKEN capable.

DEBIT

Capability indicates if instrument is DEBIT capable.

CREDIT

Capability indicates if instrument is CREDIT capable.

FAST_FUND_CROSSBORDER

Capability indicates instrument is fast fund capable for cross border transactions.

FAST_FUND_DOMESTIC

Capability indicates instrument is fast fund capable for domestic transactions.

CURRENCY_CHANGEABLE

Capability indicates instrument is eligible for Currency Change.

AUTO_DEBIT_CARD

Capability indicates instrument is debit card provisioning capable.

NO_VERIFICATION

Capability indicates instrument is no verification.

DESCRIPTOR

Capability indicates instrument supports 'descriptor' related capability. Descriptor aka Soft Descriptor is the wording which appears in the financial instrument's statement/account history during an activity with financial instrument.

ADDRESS_VERIFICATION

Capability indicates instrument supports address verification.

ADD_FUNDS

Capability indicates instrument supports add funds.

AUTH

Capability indicates instrument is auth functionality capable.

CHECK_DIGIT_VERIFICATION

Capability indicates instrument is check digit verification capable.

CONFIRM_INSTRUMENT_DETAILS

Capability indicates instrument is confirm instrument details capable.

GET_INSTRUMENT_DETAILS

Capability indicates instrument is get instrument details capable.

REFUND

Capability indicates instrument is refund capable.

WIRE_WITHDRAWAL

Capability indicates instrument is wire withdrawal capable.

WITHDRAWAL

Capability indicates instrument is withdrawal capable.

EKYC

Capability indicates instrument supports eKYC authentication process.

EXTERNAL_LOGIN

Capability indicates instrument is enternal login capable.

REAL_TIME_BALANCE

Capability indicates instrument supports Real Time Balance (RTB or Open Banking) checks for bank instrument.

CANCEL_NOT_SUPPORTED_ON_REFUND

Capability indicates instrument cancel on refund is not supported.

CAPTURE_NON_REAL_TIME

Capability indicates instrument is non real time capture operation capable.

CAPTURE_REAL_TIME

Capability indicates instrument is real time capture operation capable.

CHARGE

Capability indicates instrument is charge capable.

EXCESSIVE_CAPTURE

Capability indicates instrument is excessive capture operation capable.

INITIAL_BALANCE_INQUIRY

Capability indicates instrument is initial balance inquiry operation capable.

INSTANT_VERIFICATION_CHECK

Capability indicates the operation is an instant or immediate verification of a consumers bank account balance and consumer contact information.

INSTORE_REDEMPTION

Capability indicates the operation is an in-store redemption.

NEED_SETTLEMENT

Capability indicates the operation needs a settlement.

NO_SETTLEMENT

Capability indicates the operation doesn't need a settlement.

ONE_DIMENSIONAL_CA128

Capability indicates the operation supports one-dimensional (1D or linear) barcode CA128 scanning.

ONE_DIMENSIONAL_PDF417

Capability indicates the operation supports one-dimensional (1D or linear) barcode app PDF417 scanning.

ONE_DIMENSIONAL_QRCODE

Capability indicates the operation supports one-dimensional (1D or linear) QR code scanning.

TWO_DIMENSIONAL_CA128

Capability indicates the operation supports two-dimensional (1D or linear) barcode CA128 scanning.

TWO_DIMENSIONAL_PDF417

Capability indicates the operation supports two-dimensional (1D or linear) barcode app PDF417 scanning.

TWO_DIMENSIONAL_QRCODE

Capability indicates the operation supports two-dimensional (1D or linear) QR code scanning.

ONLINE_REDEMPTION

Capability indicates the operation is an online redemption.

ORIGINAL_CREDIT_TRANSACTION

Capability indicates the operation is an original credit transaction.

REALTIME_BALANCE_INQUIRY

Capability indicates the operation is a real-time balance inquiry.

REFUND_NON_REAL_TIME

Capability indicates the operation is a refund in non-real-time.

REFUND_REAL_TIME

Capability indicates the operation is a refund in real-time.

RELOADABLE

Capability indicates the operation is a reloadable transaction.

SUPPORT_ALL_MERCHANTS

Capability indicates the operation supports all merchants.

SUPPORT_BARCODE_SCAN

Capability indicates the operation supports barcode scanning.

ASYNC_INSTANT_PAYMENT

Capability indicates instrument supports asynchronous instant payments which typically happens in two steps. The first step represents payment initiation from PayPal, and second step represents callback coming in from an external processor.

US_NON_RESIDENT_ACCOUNT

Identify if US Bank account holder has residence address outside US, used for marking the transaction as IAT (International ACH Transfer).

mode
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The supported financial instrument (FI) mode.

Enum Value Description
NON_REAL_TIME

Non real time mode.

REAL_TIME

Real time mode.

Array of objects (Network) [ 1 .. 100 ] items

Networks for the Financial instrument.

{
  • "name": "INSTALLMENT",
  • "mode": "NON_REAL_TIME",
  • "networks": [
    • {
      • "name": "ACCEL",
      • "preferred": true,
      • "cross_border_transaction_supported": true,
      • "supported_currencies": [
        • "str"
        ],
      • "transfer_type": "WIRE",
      • "mandate_enforcement": "SEPA",
      • "network_rules": [
        • "string"
        ]
      }
    ]
}

Contract details of a currency pair.

Contract details specifies honor period, rate refresh details etc. of a contract.

rate_config_id
string [ 1 .. 4000 ] characters ([0-9]*)

Rate_config_id uniquely identifies a currency pair contract.

honor_period
required
integer [ 1 .. 86400 ]

Time in seconds to honor the rate. The honor period is upto 24 hours and can range from 1 to 86400 seconds.

rounding_rule
required
string [ 1 .. 50 ] characters ^[A-Z_]+$

Rounding rule for amount depending on the value.

Value Description
HALF_UP

Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case round up.

recurrence_period
required
string [ 1 .. 30 ] characters ^[A-Z_]+$

The Recurrence period for the rate to refresh. If the recurrence_period is DAILY then the rate will refreshed everyday at 12:00 AM and if the recurrence_period is WEEKLY then the rate will be refreshed every week at Monday 12:00 AM (PS: As of ISO standard, we have Monday as the first day of the week).

Enum Value Description
DAILY

Daily refresh.

WEEKLY

Weekly refresh.

required
Array of objects (Rate refresh times.) [ 1 .. 1000 ] items

Time in seconds when the rate will be refreshed based on the recurrence_period (DAILY,WEEKLY) attribute.

base_currency
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

Three-letter ISO 4217 alphabetical currency code.

quote_currency
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

Three-letter ISO 4217 alphabetical currency code.

start_time
required
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

Time when the honor rate will start. It is represented in ISO 8601

end_time
required
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

Time when the honor rate will expire. It is represented in ISO 8601

status
string (Represents the operation status.) [ 1 .. 22 ] characters ^[A-Z_]+$

Represents the approved status.

Enum Value Description
APPROVED

Represents the approved status.

PENDING_APPROVAL

Represents the pending status.

{
  • "rate_config_id": "string",
  • "honor_period": 1,
  • "rounding_rule": "HALF_UP",
  • "recurrence_period": "DAILY",
  • "rate_refresh_times": [
    • {
      • "rate_refresh_time": "string",
      • "rate_refresh_timezone": "string"
      }
    ],
  • "base_currency": "str",
  • "quote_currency": "str",
  • "start_time": "stringstringstringst",
  • "end_time": "stringstringstringst",
  • "status": "APPROVED"
}

Contract id uniquely defines a rate-quote-contract between PayPal and category, country.

string (Contract id uniquely defines a rate-quote-contract between PayPal and category, country.) [ 1 .. 4000 ] characters ([0-9]*)
"string"

country_code

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

country_code

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The 2-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

"st"

currency_code

The 3-character ISO-4217 currency code that identifies the currency.

string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The 3-character ISO-4217 currency code that identifies the currency.

"str"

date_time

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.

string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

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.

"stringstringstringst"

email_address

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.

string <ppaas_common_email_address_v2> (email_address) [ 3 .. 254 ] characters ^.+@[^"\-].+$

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.

"string"

Error

The error details.

name
required
string

The human-readable, unique name of the error.

message
required
string

The message that describes the error.

debug_id
required
string

The PayPal internal ID. Used for correlation purposes.

information_link
string

The information link, or URI, that shows detailed information about this error for the developer.

Array of objects (Error Details)

An array of additional details about the error.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}

Error Details

The error details. Required for client-side 4XX errors.

field
string

The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.

value
string

The value of the field that caused the error.

location
string
Default: "body"

The location of the field that caused the error. Value is body, path, or query.

issue
required
string

The unique, fine-grained application-level error code.

description
string

The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.

{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}

Exchange currency request.

Exchange currency request.

bulk_id
required
string [ 1 .. 45 ] characters .*

The unique identifier for each bulk item, enabling the client to correlate request and response.

conversion_reason
required
string [ 4 .. 1000 ] characters ^[A-Z_]+$

The reason for the currency exchange conversion.

Enum Value Description
WITHDRAW

Currency conversion is for withdrawing money out of PayPal to the linked bank account or eligible debit cards. Ex: If an account holds 10USD and initiates a local bank withdrawal, the 10USD will be first converted to Polish Zloty and then withdrawn to the local bank

FX_ON_SENDER

Currency Conversion is for purchasing goods/services. Ex: Buyer is using instrument in a different currency to fund the transaction.

FX_ON_RECEIVER

Currency Conversion is for Receiving funds. Ex: Merchant is receiving funds in a different currency than the transaction currency.

FX_ON_BALANCE_TRANSFER

Currency Conversion is for Balance transfer. Ex: Customer converting money from one holding currency to another.

NON_TRANSACTION_FX

Used when fetching rates for purposes other than transactions.

trade_type
required
string [ 3 .. 1000 ] characters ^[A-Z_]+$

The type of the currency exchange.

Enum Value Description
BUY

When you intent to buy amount specified in the request with the currency mentioned in target currency code.

SELL

When you intent to sell the amount specified in the request and receive amount in target currency.This is default trade type.

fx_id
string [ 1 .. 4000 ] characters ^[ -~]+$

A previous reference can be passed in to get a rate quote amount based on a previous rate.

required
object (Money)

The from amount for currency exchange.

target_currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The target currency code.

{
  • "bulk_id": "string",
  • "conversion_reason": "WITHDRAW",
  • "trade_type": "BUY",
  • "fx_id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_currency_code": "str"
}

Exchange currency response.

Exchange currency response.

bulk_id
string [ 1 .. 45 ] characters .*

The unique identifier for each bulk item, enabling the client to correlate request and response.

exchange_rate
string [ 1 .. 32 ] characters ^([0-9]+[.][0-9]+)$

The currency conversion exchange rate.

fee_percent
string [ 1 .. 32 ] characters ^(-?[0-9]+|-?([0-9]+)?[.][0-9]+)$

The fee percentage applied for this currency conversion.

reference_id
string [ 1 .. 4000 ] characters ^[a-zA-Z0-9!@#$&()\-`.+,/":;~_=]*$

The reference id to identify this conversion.

object (Money)

The from amount for currency exchange.

object (Money)

The to amount for currency exchange.

object (Money)

The usd equivalent to source amount

object (Money)

The usd equivalent to target amount

object (Fee Data)

In-depth information on the exchange currency fee applied to the order.

conversion_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The time the conversion is done in ISO 8601.

effective_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The effective time of exchange rate in ISO 8601.

{
  • "bulk_id": "string",
  • "exchange_rate": "string",
  • "fee_percent": "string",
  • "reference_id": "string",
  • "source_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "source_usd_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_usd_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "fee": {
    • "fee_audit_trail_id": "string",
    • "transaction_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "total_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "percent_fee": "string",
    • "fixed_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "partner_markup": "string"
    },
  • "conversion_time": "stringstringstringst",
  • "effective_time": "stringstringstringst"
}

Fee Data

In-depth information on the fee applied to the order.

fee_audit_trail_id
required
string [ 1 .. 500 ] characters ^[ -~]+$

Would determine how the spread is calculated.

required
object (Money)

transaction value of the order.

required
object (Money)

Total monetary value of the fee.

percent_fee
required
string <ppaas_common_percentage_v2> (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Percentage of the order applied in fee.

object (Money)

The amount to be charged in fee from any transaction, irrespective of the quantity or transaction amount.

partner_markup
string <ppaas_common_percentage_v2> (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The client/partner provided markup that will be included in the exchange rate and later paid out to the client/partner.

{
  • "fee_audit_trail_id": "string",
  • "transaction_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "total_fee": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "percent_fee": "string",
  • "fixed_fee": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "partner_markup": "string"
}

high_risk_category

Indicates the risk category of a merchant as per AML and Compliance checks.

string (high_risk_category) [ 1 .. 30 ] characters ^[0-9A-Z_]+$

Indicates the risk category of a merchant as per AML and Compliance checks.

Enum Value Description
HIGH_RISK

Indicates that the merchant is identified as risky by AML and Compliance team.

HIGH_RISK_WITH_EDD

Indicates that the merchant is identified as risky and requires Enhanced Due Diligence registration by AML and Compliance team.

"HIGH_RISK"

jwt

The number in string format, and pattern supports JWT, Plain(account number of the instrument), Encrypted.

string (jwt) [ 1 .. 2000 ] characters ^[A-Za-z0-9-_.+/=]+$

The number in string format, and pattern supports JWT, Plain(account number of the instrument), Encrypted.

"string"

List of category mapping values.

List of categories linked to contract_id. These are price category codes for each/multiple customers generated by the engine and cannot be x-enums.

Array ([ 1 .. 100 ] items)
string [ 1 .. 10 ] characters ^[A-Z0-9]+$

Price category that is linked to the contract.

[
  • "string"
]

merchant_segment

Indicates the type of segment merchant comes under in his business segment.

string (merchant_segment) [ 1 .. 20 ] characters ^[0-9A-Z_]+$

Indicates the type of segment merchant comes under in his business segment.

Enum Value Description
LE

Indicates the merchant belongs to Large Enterprise segment.

SMB

Indicates the merchant belongs to Small Medium Business segment.

"LE"

Money

The currency and amount for a financial transaction, such as a balance or payment due.

currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The 3-character ISO-4217 currency code that identifies the currency.

value
required
string <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The value, which might be:

  • An integer for currencies like JPY that are not typically fractional.
  • A decimal fraction for currencies like TND that are subdivided into thousandths.
For the required number of decimal places for a currency code, see Currency Codes.

{
  • "currency_code": "str",
  • "value": "string"
}

Network

The capability network.

name
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The capability Network.

Enum Value Description
ACCEL

Indicates ACCEL network support for given instrument.

AMEX

Indicates AMEX network support for given instrument..

BACS

Indicates BACS network support for given instrument.

BML

Indicates BML network support for given instrument.

CB_NATIONALE

Indicates CB_NATIONALE network support for given instrument.

CET

Indicates CET network support for given instrument.

CETELEM

Indicates CETELEM network support for given instrument.

CHAPS

Indicates CHAPS network support for given instrument.

CHASENET

Indicates CHASENET network support for given instrument.

CHINA_UNION_PAY

Indicates CHINA_UNION_PAY network support for given instrument.

COFIDIS

Indicates COFIDIS network support for given instrument.

COFINOGA

Indicates COFINOGA network support for given instrument.

DELTA

Indicates DELTA network support for given instrument.

DINERS

Indicates DINERS network support for given instrument.

DISCOVER

Indicates DISCOVER network support for given instrument.

EFTPOS

Indicates EFTPOS network support for given instrument.

ELECTRON

Indicates ELECTRON network support for given instrument.

ELO

Indicates ELO network support for given instrument.

FPS

Indicates FPS network support for given instrument.

GE

Indicates GE network support for given instrument.

HIPER

Indicates HIPER network support for given instrument.

HIPERCARD

Indicates HIPERCARD network support for given instrument.

IAV_YODLEE

Indicates IAV_YODLEE network support for given instrument.

JCB

Indicates JCB network support for given instrument.

LOCAL

Indicates LOCAL network support for given instrument.

MAESTRO

Indicates MAESTRO network support for given instrument.

MASTER_CARD

Indicates MASTER_CARD network support for given instrument.

NYCE

Indicates NYCE network support for given instrument.

OPEN_WALLET

Indicates OPEN_WALLET network support for given instrument.

PAYPAL

Indicates PAYPAL network support for given instrument.

POSTEPAY

Indicates POSTEPAY network support for given instrument.

PULSE

Indicates PULSE network support for given instrument.

PWMB

Indicates PWMB network support for given instrument.

RUPAY

Indicates RUPAY network support for given instrument.

SAN

Indicates SAN network support for given instrument.

SEPA

Indicates SEPA network support for given instrument.

SEPA_COR1

Indicates SEPA_COR1 network support for given instrument.

SEPA_CORE

Indicates SEPA_CORE network support for given instrument.

SOLO

Indicates SOLO network support for given instrument.

SSG

Indicates SSG network support for given instrument.

STAR

Indicates STAR network support for given instrument.

STAR_FINANZ

Indicates STAR_FINANZ network support for given instrument.

STAR_ACCESS

Indicates STAR_ACCESS network support for given instrument.

SWITCH

Indicates SWITCH network support for given instrument.

VISA

Indicates VISA network support for given instrument.

WIRE

Indicates WIRE network support for given instrument.

FASTER_CLEARING

Indicates FASTER_CLEARING network support for given instrument.

SYNCHRONY_FINANCIAL_SUPPORT

Indicates Synchrony Financial network support for given instrument.

REAL_TIME_PAYMENTS

Indicates REAL_TIME_PAYMENTS network support for given instrument.

preferred
boolean

Indicates whether the network is the preferred network to complete the operation.

cross_border_transaction_supported
boolean

Is cross border transaction supported.

supported_currencies
Array of strings <ppaas_common_currency_code_v2> (currency_code) [ 1 .. 100 ] items

Supported currencies for the instrument.

transfer_type
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Transfer type for particular network.

Enum Value Description
WIRE

Transfer type wire.

ELECTRONIC

Transfer type electronic.

INSTANT

Transfer type Instant.

STANDARD

Transfer type Standard.

mandate_enforcement
string [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Mandate enforcement for the network.

Enum Value Description
SEPA

Mandate enforcement.

ELECTRONIC

Mandate enforcement.

network_rules
Array of strings [ 1 .. 100 ] items

Specific rules associated with Network.

{
  • "name": "ACCEL",
  • "preferred": true,
  • "cross_border_transaction_supported": true,
  • "supported_currencies": [
    • "str"
    ],
  • "transfer_type": "WIRE",
  • "mandate_enforcement": "SEPA",
  • "network_rules": [
    • "string"
    ]
}

Object for exchange currency pricing details.

Object for exchange currency pricing details.

price_category_code
string [ 1 .. 32 ] characters ^[0-9A-Z]+$

Deprecated. Please use: ../user_profile/price_category. The price negotiation identifier with Paypal.

legal_country_code
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

Deprecated. Please use: ../user_profile/legal_country_code. The legal country code to which the exchange is associated with.

{
  • "price_category_code": "string",
  • "legal_country_code": "string"
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

Enum Value Description
add

Depending on the target location reference, completes one of these functions:

  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.

remove

Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.

replace

Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.

move

Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.

copy

Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.

test

Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.

path
string

The JSON Pointer to the target document location at which to complete the operation.

value
any (Patch Value)

The value to apply. The remove, copy, and move operations do not require a value. Since JSON Patch allows any type for value, the type property is not specified.

from
string

The JSON Pointer to the target document location from which to move the value. Required for the move operation.

{
  • "op": "add",
  • "path": "string",
  • "value": null,
  • "from": "string"
}

percentage

The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.

string <ppaas_common_percentage_v2> (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.

"string"

Phone

The phone number, in its canonical international E.164 numbering plan format.

country_code
required
string [ 1 .. 3 ] characters ^[0-9]{1,3}?$

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

national_number
required
string [ 1 .. 14 ] characters ^[0-9]{1,14}?$

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

extension_number
string [ 1 .. 15 ] characters ^[0-9]{1,15}?$

The extension number.

{
  • "country_code": "str",
  • "national_number": "string",
  • "extension_number": "string"
}

Phone info

Type of the phone and phone number.

phone_type
string (Phone Type)

The phone usage type, for example, work, home, or mobile.

Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"
object (Phone)

The phone number.

{
  • "phone_type": "FAX",
  • "phone_number": {
    • "country_code": "str",
    • "national_number": "string",
    • "extension_number": "string"
    }
}

Phone Type

The phone type.

string (Phone Type)

The phone type.

Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"
"FAX"

Portable Postal Address (Medium-Grained)

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1
string <= 300 characters

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.

address_line_2
string <= 300 characters

The second line of the address. For example, suite or apartment number.

address_line_3
string <= 100 characters

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.

admin_area_4
string <= 100 characters

The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:

  • The postal sorting code for Guernsey and many French territories, such as French Guiana.
  • The fine-grained administrative levels in China.

admin_area_3
string <= 100 characters

A sub-locality, suburb, neighborhood, or district. Smaller than admin_area_level_2. Value is:

  • Brazil. Suburb, bairro, or neighborhood.
  • India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.

admin_area_2
string <= 120 characters

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1
string <= 300 characters

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 not California. Value, by country, is:

  • UK. A county.
  • US. A state.
  • Canada. A province.
  • Japan. A prefecture.
  • Switzerland. A kanton.

postal_code
string <= 60 characters

The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_code
required
string <ppaas_common_country_code_v2> (country_code) = 2 characters ^([A-Z]{2}|C2)$

The two-character ISO 3166-1 code that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the C2 country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

object (Address Details)

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.

{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "address_line_3": "string",
  • "admin_area_4": "string",
  • "admin_area_3": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st",
  • "address_details": {
    • "street_number": "string",
    • "street_name": "string",
    • "street_type": "string",
    • "delivery_service": "string",
    • "building_name": "string",
    • "sub_building": "string"
    }
}

Rate refresh times.

List of rate refresh details having the epoch elapsed time and timezone based on merchant preference.

rate_refresh_time
required
string <ppaas_common_time_duration_v2> (Time Duration) ^P([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T(...

Duration when the rate will be refreshed based on the recurrence_period in UTC.

rate_refresh_timezone
required
string <ppaas_time_zone_v3> (time_zone) [ 1 .. 127 ] characters

Timezone of the rate_refresh_time based on merchant preference. The service handle conversion to UTC.

{
  • "rate_refresh_time": "string",
  • "rate_refresh_timezone": "string"
}

Represents the operation status.

Represents the operation status.

string (Represents the operation status.) [ 1 .. 22 ] characters ^[A-Z_]+$

Represents the operation status.

Enum Value Description
APPROVED

Represents the approved status.

PENDING_APPROVAL

Represents the pending status.

"APPROVED"

Request Object for bulk exchange currency.

Request Object for bulk exchange currency.

required
Array of objects (Exchange currency request.) [ 1 .. 20 ] items

List of exchange currency request. The requests would be processed sequentially.

{
  • "exchange_currency_requests": [
    • {
      • "bulk_id": "string",
      • "conversion_reason": "WITHDRAW",
      • "trade_type": "BUY",
      • "fx_id": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "target_currency_code": "str"
      }
    ]
}

Request Object for exchange currency.

Request Object for exchange currency.

conversion_reason
required
string [ 4 .. 1000 ] characters ^[A-Z_]+$

The reason for the currency exchange conversion.

Enum Value Description
WITHDRAW

Currency conversion is for withdrawing money out of PayPal to the linked bank account or eligible debit cards. Ex: If an account holds 10USD and initiates a local bank withdrawal, the 10USD will be first converted to Polish Zloty and then withdrawn to the local bank

FX_ON_SENDER

Currency Conversion is for purchasing goods/services. Ex: Buyer is using instrument in a different currency to fund the transaction.

FX_ON_RECEIVER

Currency Conversion is for Receiving funds. Ex: Merchant is receiving funds in a different currency than the transaction currency.

FX_ON_EXISTING_RATE

Currency conversion is on the previous rate used Ex: The rate used is in the audit trail, if client want to use already known exchange rate.

FX_ON_BALANCE_TRANSFER

Currency Conversion is for Balance transfer. Ex: Customer converting money from one holding currency to another.

NON_TRANSACTION_FX

Used when fetching rates for purposes other than transactions.

MARKET_RATE_FX

Use customer rate for conversion without fee.

trade_type
required
string [ 3 .. 1000 ] characters ^[A-Z_]+$

The type of the currency exchange.

Enum Value Description
BUY

When you intent to buy amount specified in the request with the currency mentioned in target currency code.

SELL

When you intent to sell the amount specified in the request and receive amount in target currency.This is default trade type.

fx_id
string [ 1 .. 4000 ] characters ^[ -~]+$

A previous reference can be passed in to get a rate quote amount based on a previous rate.

required
object (Money)

The from amount for currency exchange.

target_currency_code
required
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The target currency code.

object (Object for exchange currency pricing details.)

Deprecated. Use price_category and legal_country_code under user_profile.

{
  • "conversion_reason": "WITHDRAW",
  • "trade_type": "BUY",
  • "fx_id": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_currency_code": "str",
  • "pricing_details": {
    • "price_category_code": "string",
    • "legal_country_code": "string"
    }
}

Request Object for exchange_rate_quote.

Request Object for exchange_rate_quote.

base_amount
string [ 1 .. 32 ] characters ^([0-9]+[.][0-9]+)$

The transaction amount that needs to be converted. If this parameter is not present in the request, the quote rate for a single unit of base currency is received in response.

fx_id
string [ 1 .. 4000 ] characters ^[ -~]+$

A previous reference ID obtained in the earlier Quote API call response. You can use fx_id to get the rate of the same currency pair with different amount of the base currency when the rate is not expired.

base_currency
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The currency code of the base amount to be converted for the presentment and in which the final transaction amount needs to be settled into merchant PayPal business account. This could be your primary currency, or any other PayPal supported holding currency. You can find currency codes here.

quote_currency
string <ppaas_common_currency_code_v2> (currency_code) = 3 characters

The currency code in which the conversion should take place using this API. This is the currency in which the transaction is performed, and the transaction amount gets converted into base currency.

markup_percent
string <ppaas_common_percentage_v2> (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The percentage of the merchant or partner spread to be included as part of the exchange rate. markup_percent can range from 0 to 100.

{
  • "base_amount": "string",
  • "fx_id": "string",
  • "base_currency": "str",
  • "quote_currency": "str",
  • "markup_percent": "string"
}

Request Object for quoting exchange rates.

Request Object for quoting exchange rates.

organization
string [ 2 .. 100 ] characters ^\w{2,20}(\/\w{2,20})*$

Organization this managed account belongs to, in the partner's hierarchy, in the form of a path.

required
Array of objects (Request Object for exchange_rate_quote.) [ 1 .. 250 ] items

The details necessary to request an exchange rate. The possible details (parameters) you can specify/pass in the quote_items array are: base_currency, base_amount, quote_currency, markup_percent and fx_id.

two_way_quote
boolean

Indicator to fetch both sell and buy quotes for base or quote currency pair.

{
  • "organization": "string",
  • "quote_items": [
    • {
      • "base_amount": "string",
      • "fx_id": "string",
      • "base_currency": "str",
      • "quote_currency": "str",
      • "markup_percent": "string"
      }
    ],
  • "two_way_quote": true
}

Response object for bulk exchange currency.

Response object for bulk exchange currency.

Array of objects (Exchange currency response.) [ 1 .. 100 ] items

List of exchange currency responses.

{
  • "exchange_currency_responses": [
    • {
      • "bulk_id": "string",
      • "exchange_rate": "string",
      • "fee_percent": "string",
      • "reference_id": "string",
      • "source_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "target_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "source_usd_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "target_usd_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "fee": {
        • "fee_audit_trail_id": "string",
        • "transaction_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "total_fee": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "percent_fee": "string",
        • "fixed_fee": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "partner_markup": "string"
        },
      • "conversion_time": "stringstringstringst",
      • "effective_time": "stringstringstringst"
      }
    ]
}

Response object for exchange currency.

Response object for exchange currency.

exchange_rate
string [ 1 .. 32 ] characters ^([0-9]+[.][0-9]+)$

The currency conversion exchange rate.

fee_percent
string [ 1 .. 32 ] characters ^(-?[0-9]+|-?([0-9]+)?[.][0-9]+)$

The fee percentage applied for this currency conversion.

reference_id
string [ 1 .. 4000 ] characters ^[a-zA-Z0-9!@#$&()\-`.+,/":;~_=]*$

The reference id to identify this conversion.

object (Money)

The from amount for currency exchange.

object (Money)

The to amount for currency exchange.

object (Money)

The usd equivalent to source amount

object (Money)

The usd equivalent to target amount

object (Fee Data)

In-depth information on the exchange currency fee applied to the order.

conversion_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The time the conversion is done in ISO 8601.

effective_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The effective time of exchange rate in ISO 8601.

{
  • "exchange_rate": "string",
  • "fee_percent": "string",
  • "reference_id": "string",
  • "source_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "source_usd_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "target_usd_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "fee": {
    • "fee_audit_trail_id": "string",
    • "transaction_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "total_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "percent_fee": "string",
    • "fixed_fee": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "partner_markup": "string"
    },
  • "conversion_time": "stringstringstringst",
  • "effective_time": "stringstringstringst"
}

Response object for fx service exchange currency.

Response object for fx service exchange currency.

exchange_rate
required
string [ 1 .. 32 ] characters ^([0-9]+[.][0-9]+)$

The exchange rate for conversion of a single unit of base currency. It may include the percentage of client/partner markup if markup_percent is passed in the request.

fx_id
string [ 1 .. 4000 ] characters ^[ -~]+$

A unique reference ID that can be used in further Quote API calls.

required
object (Money)

The amount that needs to be converted. If this parameter was not passed in the request, the value of base_amount is considered as 1 by default.

required
object (Money)

The amount in desired currency after conversion.

expiry_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The time until exchange_rate will be valid for settlement. It is represented in ISO 8601. The time is determined at the time of contract agreement.

rate_refresh_time
string <ppaas_date_time_v3> (date_time) [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...

The time at which new exchange rates will be available next for this currency pair. The frequency is determined at the time of contract agreement.

{
  • "exchange_rate": "string",
  • "fx_id": "string",
  • "base_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "quote_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "expiry_time": "stringstringstringst",
  • "rate_refresh_time": "stringstringstringst"
}

Response Object for quoting exchange rates.

Response Object for quoting exchange rates.

required
Array of objects (Response object for fx service exchange currency.) [ 1 .. 500 ] items

Array of exchange rate details. It contains base_amount, quote_amount, exchange_rate, trade_rate, expiry_time, rate_refresh_time and fx_id.

{
  • "exchange_rate_quotes": [
    • {
      • "exchange_rate": "string",
      • "fx_id": "string",
      • "base_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "quote_amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "expiry_time": "stringstringstringst",
      • "rate_refresh_time": "stringstringstringst"
      }
    ]
}

Status of the Instrument

Status of the instrument, indicates whether it is available for clients.

string (Status of the Instrument) [ 1 .. 12 ] characters ^[A-Z_]+$

Status of the instrument, indicates whether it is available for clients.

Enum Value Description
OPEN

Status of the instrument - OPEN. Instrument is available for transactions.

CLOSED

Status of the instrument - CLOSED. Instrument is unavailable for transactions.

"OPEN"

Sub balance resource

Sub balance resource.

type
string (The specific type of the balance account) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

Type of balance.

Enum Value Description
AVAILABLE

Available balance.

CC_FUNDED

Amount received from credit card transactions.

EXIT_LIMIT

Exit Limit.

EXTERNAL_HOLD

External hold.

GIFT_CARD

Gift card balance.

GUEST_BALANCE

Guest balance for temporary usage like PUI and PAD.

HOLD

Hold balance because of risk.

LIMITATION_RESERVE

Reserve balance due to limitations.

MERCHANT_SPECIFIC_BALANCE

Payable or receivable balance aka MSB.

PENDING_REVERSAL

Buffer balance kept for pending reversals.

TOTAL_BALANCE

Total balance, includes holds, reserves and balance.

VARIABLE_RESERVES

Reserve balance.

DELAYED_SETTLEMENT

Delayed settlement.

EBAY_NON_PERFORMER

EBay non performer.

JUMP_START

Jump start.

MINIMUM_BALANCE

Minimum balance.

MPLT_HOLD

Transaction hold on seller's account.

TRANS_LEVEL_HOLD

Transaction hold which is placed when buyer is fraudulent.

AUTHORIZED_EXTERNAL_UNCLEARED_FUNDS

Authorized external uncleared funds.

DYNAMIC_HOLD

Transaction hold to mitigate fraud due to insufficient funds on outstanding transaction.

UNCLEARED_FUNDS

Disbursement to Balance should be UNCLEARED_FUNDS when funding source is ECHECK.

TAX_HOLD

Transaction hold when tax identifier information is not available.

USER_CONSENT_HOLD

Transaction hold when user has not consented on the latest terms and conditions available.

object (Money)

Amount along with currency of balance account.

{
  • "type": "AVAILABLE",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}

The specific type of the balance account

The specific type of the balance account.

string (The specific type of the balance account) [ 1 .. 255 ] characters ^[0-9A-Z_]+$

The specific type of the balance account.

Enum Value Description
AVAILABLE

Available balance.

CC_FUNDED

Amount received from credit card transactions.

EXIT_LIMIT

Exit Limit.

EXTERNAL_HOLD

External hold.

GIFT_CARD

Gift card balance.

GUEST_BALANCE

Guest balance for temporary usage like PUI and PAD.

HOLD

Hold balance because of risk.

LIMITATION_RESERVE

Reserve balance due to limitations.

MERCHANT_SPECIFIC_BALANCE

Payable or receivable balance aka MSB.

PENDING_REVERSAL

Buffer balance kept for pending reversals.

TOTAL_BALANCE

Total balance, includes holds, reserves and balance.

VARIABLE_RESERVES

Reserve balance.

DELAYED_SETTLEMENT

Delayed settlement.

EBAY_NON_PERFORMER

EBay non performer.

JUMP_START

Jump start.

MINIMUM_BALANCE

Minimum balance.

MPLT_HOLD

Transaction hold on seller's account.

TRANS_LEVEL_HOLD

Transaction hold which is placed when buyer is fraudulent.

AUTHORIZED_EXTERNAL_UNCLEARED_FUNDS

Authorized external uncleared funds.

DYNAMIC_HOLD

Transaction hold to mitigate fraud due to insufficient funds on outstanding transaction.

UNCLEARED_FUNDS

Disbursement to Balance should be UNCLEARED_FUNDS when funding source is ECHECK.

TAX_HOLD

Transaction hold when tax identifier information is not available.

USER_CONSENT_HOLD

Transaction hold when user has not consented on the latest terms and conditions available.

"AVAILABLE"

Time Duration

The ISO-8601-formatted length of time in years, months, weeks, days, hours, minutes, and seconds.

Note: The format is PyYmMdDThHmMsS. When an amount is zero, you can omit it. Because week cannot co-exist with other time components in ISO-8601 duration, specify P7D. Make provisions to incorporate the effects of daylight savings time.

For more information, see durations.

string <ppaas_common_time_duration_v2> (Time Duration) ^P([0-9]+Y)?([0-9]+M)?([0-9]+W)?([0-9]+D)?(T(...

The ISO-8601-formatted length of time in years, months, weeks, days, hours, minutes, and seconds.

Note: The format is PyYmMdDThHmMsS. When an amount is zero, you can omit it. Because week cannot co-exist with other time components in ISO-8601 duration, specify P7D. Make provisions to incorporate the effects of daylight savings time.

For more information, see durations.

"string"

time_zone

The time zone, in Internet Assigned Numbers Authority (IANA) time zone (tz) database format. A valid value is America/New_York or Etc/UTC. Do not use ambiguous, non-qualified tz database values, such as EST or GB. Before you include this type in your interface, consider whether it is appropriate to convey time zone information with your type. At the time of display to the user, transform this value from UTC. Typically, this type is associated with user-preference APIs.

string <ppaas_time_zone_v3> (time_zone) [ 1 .. 127 ] characters

The time zone, in Internet Assigned Numbers Authority (IANA) time zone (tz) database format. A valid value is America/New_York or Etc/UTC. Do not use ambiguous, non-qualified tz database values, such as EST or GB. Before you include this type in your interface, consider whether it is appropriate to convey time zone information with your type. At the time of display to the user, transform this value from UTC. Typically, this type is associated with user-preference APIs.

"string"