PayPal

Description

PayPal is an online payment service offered by PayPal Inc. The customer is redirected to a payment site hosted by PayPal and returns back to the merchant website after completing the transaction.

Availability

Available for merchants with PayPal enabled on their account configuration.

Transaction Types

The following transaction types are currently available:

• Payment — one-time payments (payment_type: paypal)
• Refund — full and partial refunds
• Payout — send funds to a customer's PayPal account (payout_email required)
• Authorize, Capture, and Reverse — separate authorization and capture for one-time payments
• PayPal Subscriptions — create via Payment API; manage with Cancel and Revise

Not supported: standard MIT recurring

PayPal does not support merchant-initiated recurring payments using recurring: 1 and original_transaction_id (the card-style flow where you trigger each subsequent charge).

For recurring billing with PayPal, use PayPal Subscriptions only: set recurring: 1, amount: 0, and paypal_plan_id on the initial payment. PayPal triggers future charges; our platform creates child transactions and sends postbacks to your postback_url.

Integration Types

The following integration type is currently available:

• Payment Page Redirect

PayPal Subscriptions

To implement recurring billing with PayPal, use the PayPal Subscriptions flow.

This differs from standard MIT recurring (cards, SEPA, etc.): PayPal controls when subscription charges run. You do not call POST /rest/payment again with original_transaction_id for each billing cycle.

PayPal Subscriptions prerequisites

You should familiarize yourself with PayPal Subscriptions concepts first.

See:

• Subscriptions API
• Catalogue Products API
• Plan API

Creation of catalogue products and plans

When creating a PayPal Subscription through our API, you must already have a PayPal Plan created on PayPal side. Then pass paypal_plan_id when creating the subscription via Payment API.

Catalogue Product and Plan management must be done separately through PayPal APIs before creating subscriptions through our API.

How PayPal Subscriptions work

1. Create a Catalogue Product using PayPal APIs (outside our systems): official documentation.
2. Create a Plan using PayPal APIs (outside our systems): official documentation.
3. Create the subscription with POST /rest/payment (payment_type: paypal, recurring: 1, amount: 0, paypal_plan_id).
4. Redirect the customer to the URL in action_data and let them approve the subscription.
5. Our systems track follow-up subscription charges and send postbacks to the original transaction postback_url.

APIs for PayPal Subscriptions

Action	API
Create subscription	Payment API
Cancel subscription	Cancel API
Update plan, quantity, or shipping	Revise API

PayPal Subscriptions required parameters

Use the same base parameters as in a standard /rest/payment request, with the additions below.

Parameter	Required	Comments
recurring	YES	Must be 1
amount	YES	Must be 0. Future amounts come from the PayPal Plan.
paypal_plan_id	YES	PayPal Plan ID
paypal_subscription_start_time	NO	Subscription start time. If omitted, starts immediately. Must follow RFC 3339 format, e.g. 2021-09-29T11:47:25Z.
paypal_subscription_quantity	NO	Quantity of items in the plan. Only when the plan supports quantities.

Provide first_name, last_name, and email in the billing address for subscription setup. Shipping address parameters are required when the plan is for physical goods.

Payment API

Payment API Request

payment_typeStringrequired

paypal

recurringIntegerrequired

Must be 1

order_idStringrequired

Any alphanumeric string to identify the Merchant's order

amountFloatrequired

Must be 0. Future billing amounts are defined by the PayPal Plan

currencyStringrequired

3 letter currency code

postback_urlStringrequired

The URL for updates about transaction status are posted

success_urlStringrequired

Where to redirect the user after a successful transaction

error_urlStringrequired

Where to redirect the user after a failed transaction

first_nameStringrequired

Customer's first name (billing address)

last_nameStringrequired

Customer's last name (billing address)

emailStringrequired

Customer's email address

paypal_plan_idStringrequired

PayPal Plan ID created in PayPal (outside our API)

paypal_subscription_start_timeString

Subscription start time in RFC 3339 format, e.g. 2021-09-30T20:47:25Z. Starts immediately when omitted

paypal_subscription_quantityInteger

Quantity within the plan. Only when the plan supports quantities

shipping_costsFloat

Shipping costs when the plan includes shipping

shipping_addressString

Street address. Required with other shipping fields when the plan is for physical goods

shipping_cityString

City of the shipping address

shipping_postal_codeString

Postal code of the shipping address

shipping_stateString

State or region of the shipping address

shipping_countryString

Country code (ISO 3166-1 alpha-2) of the shipping address

shipping_first_nameString

Customer first name for shipping

shipping_last_nameString

Customer last name for shipping

This example creates a PayPal Subscription. See the Create Payment API reference for common and billing address parameters. Include shipping fields when the plan requires physical delivery.

Example Request

POST /rest/payment
Authorization: Basic <base64(api_key:api_password)>
Content-Type: application/json
{
"payment_type": "paypal",
"recurring": "1",
"order_id": "123000",
"amount": "0",
"currency": "EUR",
"postback_url": "https://your-postback.url.com",
"success_url": "https://your-success.url.com",
"error_url": "https://your-error.url.com",
"first_name": "Max",
"last_name": "Mustermann",
"email": "max.m@test.com",
"address": "Hellersbergstr. 14",
"city": "Neuss",
"postal_code": "41460",
"state": "NW",
"country": "DE",
"shipping_address": "2211 N First Street",
"shipping_city": "San Jose",
"shipping_postal_code": "95131",
"shipping_state": "CA",
"shipping_country": "US",
"shipping_first_name": "Max",
"shipping_last_name": "Mustermann",
"paypal_plan_id": "P-6UK2193323222643NMFJN66Q",
"shipping_costs": "10",
"paypal_subscription_quantity": 1,
"paypal_subscription_start_time": "2021-09-30T20:47:25Z"
}

Payment API Response

transaction_idString

ID of the created transaction

payment_typeString

Payment type of the transaction

order_idString

Order ID of the transaction

error_codeInteger

Error code for the response

status_codeInteger

Status code of the transaction

statusString

Status of the transaction (typically pending until the customer approves the subscription)

client_actionString

Indicates the required client-side action. Value: redirect

action_dataObject

Contains url — redirect the customer to this PayPal URL to approve the subscription

Example Response

{
"transaction_id": "dbd3ab13-38f3-49da-9e12-47ef445b0b72",
"payment_type": "paypal",
"order_id": "123000",
"error_code": 0,
"status_code": 2,
"status": "pending",
"client_action": "redirect",
"action_data": {
  "url": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-0M029980WL960863C"
}
}

Redirect the customer to the action_data.url. After approval, the customer is redirected to your success_url, and the system starts tracking transactions from this subscription.

Postbacks

For the full list of payment postback fields, see the Payment API. For refund postbacks, see the Refund API. Subscription charge postbacks are sent to the original subscription transaction postback_url. For retry policy and signature verification, see Postbacks.