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 charge
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:
- Basic details: Provide the amount, currency, payment method, payment descriptor, merchant references.
- 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.
- Consumer details (optional): Include the consumer's name and billing address details.
- Order details (optional): Include shipping details and basket contents to enhance the user experience during payment authentication.
- Authentication settings (optional): Provide authentication-specific data, such as the return URL for the REDIRECT authentication type. It is strongly recommended to configure all supported authentication types upfront, regardless of the payment method, 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": false,
"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¤cy=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. Pick the desired authentication method
The payment charge is now inAUTHENTICATION_PENDING and requires consumer authentication.
PPRO’s API leverages a standardized set of authentication types to abstract various payment flows. The API response returns all authentication types available for the specified payment method. Select the most appropriate and supported authentication method based on the payment context. For example, when a payment is initiated from a native mobile app (rather than a web browser), APP_INTENT is preferred, if available.
Learn more about payment authentication and the required steps to successfully complete the authentication process.
The most commonly used authentication type is REDIRECT. To initiate this flow, redirect the browser, either in the current tab or a pop-up window, to the provided requestUrl using the specified requestMethod.
3. Handle the payment result
After successful authentication, the payment provider, scheme, or network 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 for the REDIRECT flow, the consumer is returned to the specified returnUrl.
Check the payment status by making a GET /v1/payment-charges/{paymentChargeId}. Use the Status that you received to display the payment outcome to the consumer.
Request
GET /v1/payment-charges/{paymentChargeId}
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": "CAPTURE_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¤cy=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:24.228Z",
"updatedAt": "2025-04-23T18:22:24.228Z",
},
{
"id": "authz_CMWwx9HnCYQa5fTMZrJKn",
"amount": 1000,
"status": "AUTHORIZED",
"merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
"createdAt": "2025-04-23T18:22:33.890Z",
"updatedAt": "2025-04-23T18:22:33.890Z",
}
],
"captures": [],
"refunds": [],
"voids": [],
"createdAt": "2025-04-23T18:22:24.003Z",
"updatedAt": "2025-04-23T18:22:33.890Z",
"_links": {
"authorizations": {
"href": "/v1/payment-charges/charge_9MFbAbgnFkYDhZjWLNSP4/authorizations"
},
"captures": {
"href": "/v1/payment-charges/charge_9MFbAbgnFkYDhZjWLNSP4/captures"
},
"refunds": {
"href": "/v1/payment-charges/charge_9MFbAbgnFkYDhZjWLNSP4/refunds"
},
"voids": {
"href": "/v1/payment-charges/charge_9MFbAbgnFkYDhZjWLNSP4/voids"
}
}
}
4. Capture a payment
While an authorization is merely a hold on the amount specified, a capture initiates the movement of funds. Captures can be submitted through the API using the Create capture call.
PPRO supports multiple partial captures up to the authorized amount. Refer to the specific payment method documentation to verify capture support. Learn more about captures.
Sending autoCapture: trueduring the payment charge creation will automatically capture the full amount upon successful authorization, resulting in the payment charge ending with a CAPTURED status.
Request
POST /v1/payment-charges/{paymentChargeId}/captures
{
"amount": 1000,
"merchantCaptureReference": "YOUR_CAPTURE_REFERENCE"
}
Response
{
"id": "capture_w60qDSiYVgzrjdhOsZRLG",
"amount": 1000,
"status": "CAPTURED",
"merchantCaptureReference": "YOUR_CAPTURE_REFERENCE",
"createdAt": "2025-04-23T18:58:08.100Z",
"updatedAt": "2025-04-23T18:58:08.100Z",
"_links": {
"payment_charge": {
"href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d"
}
}
}
5. Refund a payment
PPRO supports full and partial refunds up to the captured amount. Refer to the specific payment method documentation to verify capture support. Learn more about refunds.
Captures can be submitted through the API using the Create refund call.
Request
POST /v1/payment-charges/{paymentChargeId}/refunds
{
"amount": 600,
"merchantRefundReference": "YOUR_REFUND_REFERENCE"
}
Response
{
"id": "refund_iKCiv8S92fgDjFpDiV5R6",
"amount": 600,
"status": "REFUNDED",
"merchantRefundReference": "YOUR_REFUND_REFERENCE",
"createdAt": "2025-04-30T08:42:53.849Z",
"updatedAt": "2025-04-30T08:42:53.849Z",
"_links": {
"payment_charge": {
"href": "/v1/payment-charges/charge_SR2P8Dd9WI5x2naacLR7d"
}
}
}
Updated 21 days ago