Documentation

Quickstart: LPMs

💡

This guide assumes a basic understanding of PPRO's core API objects and common API functionality.

PPRO provides access to payment products across the globe, covering both local payment methods and cards. This guide focuses on the technical integration for accepting local payment methods.

1. Create a payment

Create a payment charge by submitting a POST request to /v1/payment-charges.

The payment charge is designed with a rich data model that enables a single integration and reuse of data points across many payment methods. To minimize the upfront effort, many fields are optional by default (unless the specified payment method requires the data). This approach enables you to build the expected payload incrementally.

The payment charge expects data points around:

  1. Basic details: Provide the amount, currency, payment method, payment descriptor, merchant references.
  2. Instrument details (optional): Include information about the funding source, if applicable. This is generally not required for LPMs, except in specific cases - such as supplying bank account details for SEPA Direct Debit.
  3. Consumer details (optional): Include the consumer's name and billing address details.
  4. Order details (optional): Include shipping details and basket contents to enhance the user experience during payment authentication.
  5. Authentication settings (optional): Provide authentication-specific data, such as the return URL for the REDIRECT authentication type. It is strongly recommended that you provide settings for all supported authentication types so that you can easily adopt additional flows if they become available.

Request

POST /v1/payment-charges

{
  "paymentMethod": "PAYMENT_METHOD",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "initiator": "CONSUMER",
  "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "UNSCHEDULED",
  "amount": {
    "value": 1000,
    "currency": "GBP"
  },
  "consumer": {
    "billingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+4411223344556",
      "street": "20 Midtown, 20 Procter St",
      "postalCode": "WC1V 6NX",
      "city": "London",
      "country": "GB"
    },
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+4411223344556",
    "country": "GB",
    "locale": "en-GB"
  },
  "order": {
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+4411223344556",
      "street": "20 Midtown, 20 Procter St",
      "postalCode": "WC1V 6NX",
      "city": "London",
      "country": "GB"
    },
    "orderItems": [
      {
        "name": "White T-Shirt",
        "quantity": 1,
        "amount": 1000
      }
    ],
    "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
    "totalTaxAmount": 167
  },
  "authenticationSettings": [
    {
      "type": "APP_INTENT",
      "settings": {
        "mobileIntentUri": "webshop://paymentresponse?123"
      }
    },
    {
      "type": "SCAN_CODE",
      "settings": {
        "scanBy": "2025-11-03T11:23:47.123Z"
      }
    },
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    },
    {
      "type": "MULTI_FACTOR",
      "settings": {}
    }
  ],
  "autoCapture": true,
  "webhooksUrl": "https://notification.service.com/"
}

Response

{
  "id": "charge_SR2P8Dd9WI5x2naacLR7d",
  "paymentMethod": "PAYMENT_METHOD",
  "paymentMedium": "ECOMMERCE",
  "initiator": "CONSUMER",
  "scheduleType": "UNSCHEDULED",
  "instrumentId": "instr_qfaQTQjKjWa2vamCZswnQ",
  "currency": "GBP",
  "country": "GB",
  "paymentDescriptor": "YOUR_PAYMENT_DESCRIPTOR",
  "status": "AUTHENTICATION_PENDING",
  "consumer": {
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+4411223344556",
    "country": "GB",
    "locale": "en-GB",
    "billingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+4411223344556",
      "street": "20 Midtown, 20 Procter St",
      "postalCode": "WC1V 6NX",
      "city": "London",
      "country": "GB"
    }
  },
  "order": {
    "orderItems": [
      {
        "name": "White T-Shirt",
        "quantity": 1,
        "amount": 1000
      }
    ],
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "phoneNumber": "+4411223344556",
      "street": "20 Midtown, 20 Procter St",
      "postalCode": "WC1V 6NX",
      "city": "London",
      "country": "GB"
    },
    "industryData": [],
    "orderReferenceNumber": "YOUR_ORDER_REFERENCE_NUMBER",
    "totalTaxAmount": 167
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    },
    {
      "details": {
        "mobileIntentUri": "paymentmethod://paymentrequest?token=AAAAAAABBBBB"
      },
      "type": "APP_INTENT"
    },
    {
      "type": "MULTI_FACTOR"
    }, 
    {
      "details": {
        "codePayload": "paymentmethod://open/paymentrequest?amount=1000&currency=GBP&from=QR",
        "codeImage": "https://qr.ppro.com/image.png?payload=aWQ9YWJjJmFtb3Vuk9VVNEJmZyb209UVI",
        "codeDocument": "cdn.ppro.com//linktocodedocument",
        "scanBy": "2025-11-03T11:23:47.123Z"
        "codeType": "QR"
      },
      "type": "SCAN_CODE"
    }
  ],
  "authorizations": [
    {
      "id": "authz_n0QHu8tKSz9Lx6HK8jt7Y",
      "amount": 1000,
      "status": "AUTHENTICATION_PENDING",
      "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
      "createdAt": "2025-04-23T18:22:25.104Z",
      "updatedAt": "2025-04-23T18:22:25.104Z"
    }
  ],
  "captures": [],
  "refunds": [],
  "voids": [],
  "createdAt": "2025-04-23T18:22:24.890Z",
  "updatedAt": "2025-04-23T18:22:25.104Z",
  "_links": {
    "authorizations": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d/authorizations"
    },
    "captures": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d/captures"
    },
    "refunds": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d/refunds"
    },
    "voids": {
      "href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d/voids"
    }
  }
}

2. Authenticate the payment

The payment charge is now inAUTHENTICATION_PENDING and requires consumer authentication.

PPRO's API reuses a set of standard authentication types to encapsulate the different payment flows; the most used is the REDIRECT type. In the REDIRECT authentication type, the merchant is expected to:

  1. If it is an in-browser experience, redirect the consumer to therequestUrl value.
  2. If it is a native application, and the functionality is supported by the payment method & provider, trigger the mobileIntentUri value to enable the native provider application to handle the authentication UX natively.

After a configured time-to-live (default 24 hours), the Payment Charge transitions to a terminal DISCARDED status if not actioned by the consumer or merchant.

Learn more about the different Payment Authentication methods.

3. Handle the payment result

After successful authentication, the provider returns the authorization outcome. Learn more about Payment Authorization.

The Payment Charge object is updated to reflect the authorization outcome, a webhook is dispatched to the specified webhooksUrl and the consumer is redirected to the specified requestUrl.

You can fetch the Payment Charge by ID as described below and display the outcome to the consumer.

GET /v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF:

Response:

{
  "id": "charge_wKFAib6E4wkAAdVOaVIEF",
  "paymentMethod": "MOCK",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "UNSCHEDULED",
  "instrumentId": "instr_aTj6zrTb1aWKf49tg2Sjt",
  "currency": "EUR",
  "paymentDescriptor": "Acme - ORDER 1234",
  "status": "CAPTURE_PENDING",
  "consumer": {
    "name": "John Smith"
  },
  "order": {
    "orderItems": [
      {
        "name": "White T-Shirt",
        "quantity": 1,
        "amount": 1000
      }
    ],
    "industryData": []
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://mock-processor-public.stg.eu.dp.ppro.com/authenticator.html?payment-charge-id=charge_wKFAib6E4wkAAdVOaVIEF",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ],
  "authorizations": [
    {
      "id": "authz_uuUaAkw1qOZGu5Atyz8j8",
      "amount": 1000,
      "status": "AUTHENTICATION_PENDING",
      "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
      "createdAt": "2023-09-05T18:53:40.892Z",
      "updatedAt": "2023-09-05T18:53:40.892Z"
    },
    {
      "id": "authz_bPLT0G8ZoXH0gwYeWTNRf",
      "amount": 1000,
      "status": "AUTHORIZED",
      "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
      "createdAt": "2023-09-05T18:56:13.676Z",
      "updatedAt": "2023-09-05T18:56:13.676Z"
    }
  ],
  "captures": [],
  "refunds": [],
  "voids": [],
  "createdAt": "2023-09-05T18:53:40.812Z",
  "updatedAt": "2023-09-05T18:56:13.675Z",
  "_links": {
    "authorizations": {
      "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/authorizations"
    },
    "captures": {
      "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/captures"
    },
    "refunds": {
      "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/refunds"
    },
    "voids": {
      "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/voids"
    }
  }
}

4. Capture a payment

While an authorization is merely a hold on the amount specified, a capture triggers the movement of funds. Captures can be initiated through the API by interacting with the capture collection.

PPRO supports multiple partial captures up to the authorized amount.

Sending autoCapture: trueduring the Payment Charge initialization will result in automatically capturing the full amount on successful authorization and the Payment Charge ending in the CAPTURED status instead.

Learn more about captures.

POST /v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/captures

{
  "amount": 1000,
  "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE"
}

Response:

{
    "id": "capture_KyoLsrxHGWSH000bDgRSu",
    "amount": 1000,
    "status": "CAPTURED",
    "merchantCaptureReference": "YOUR_CAPTURE_REFERENCE",
    "createdAt": "2023-09-05T19:20:36.008Z",
    "updatedAt": "2023-09-05T19:20:36.008Z",
    "_links": {
        "payment_charge": {
            "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF"
        }
    }
}

5. Refund a payment

PPRO's API supports full and partial refunds for a given Payment Charge by interacting with the refund collection.

Learn more about refunds.

POST /v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF/refunds

{
  "amount": 600,
  "merchantRefundReference": "YOUR_REFUND_REFERENCE"
}

Response:

{
    "id": "refund_iKCiv8S92fgDjFpDiV5R6",
    "amount": 600,
    "status": "REFUNDED",
    "merchantRefundReference": "YOUR_REFUND_REFERENCE",
    "createdAt": "2023-09-06T08:42:53.849Z",
    "updatedAt": "2023-09-06T08:42:53.849Z",
    "_links": {
        "payment_charge": {
            "href": "/v1/payment-charges/charge_wKFAib6E4wkAAdVOaVIEF"
        }
    }
}

Updated about 12 hours ago