Quickstart: DPMs

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

PPRO's APIs provide access to payment products across the globe, covering both local payment methods and card products. This guide focuses on the technical integration for accepting local payment methods.

💡
Sandbox vs. Live APIs
Live API: <https://api.eu.ppro.com>
Sandbox API: <https://api.sandbox.eu.ppro.com>

1. Initialize a payment

You 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 customer integration and reuse of data points across many payment providers. To minimize the upfront effort our customers need for the integration, 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: include the amount, currency, payment method, payment descriptor, merchant references, whether to auto-capture the authorization, the webhook endpoint for asynchronous notifications and the return URL for redirected authentications.
Instrument details (optional): provide details of the funding source. This is not required for the majority of LPMs, with few exceptions (e.g. PayPal Account ID)
Consumer details (optional): include the consumer's name and billing address details.
Order details (optional) include shipping details and basket contents, this enables digital invoice integrations and better UX during Payment Authentication.

Example request for a MOCK one-time payment

POST /v1/payment-charges

{
  "paymentMethod": "MOCK",
  "merchantPaymentChargeReference": "YOUR_PAYMENT_CHARGE_REFERENCE",
  "paymentDescriptor": "Acme - ORDER 1234",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "consumer": {
    "name": "John Smith"
  },
  "order": {
    "orderItems": [
      {
        "name": "White T-Shirt",
        "quantity": 1,
        "amount": 1000
      }
    ]
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://acme-merchant.com/return"
      }
    }
  ],
  "webhooksUrl": "https://acme-merchant.com/webhooks"
}

Response:

{
  "id": "charge_wKFAib6E4wkAAdVOaVIEF",
  "paymentMethod": "MOCK",
  "paymentMedium": "ECOMMERCE",
  "scheduleType": "UNSCHEDULED",
  "instrumentId": "instr_aTj6zrTb1aWKf49tg2Sjt",
  "currency": "EUR",
  "paymentDescriptor": "Acme - ORDER 1234",
  "status": "AUTHENTICATION_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"
    }
  ],
  "captures": [],
  "refunds": [],
  "voids": [],
  "createdAt": "2023-09-05T18:53:40.812Z",
  "updatedAt": "2023-09-05T18:53:40.892Z",
  "_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"
    }
  }
}

2. Authenticate the payment

The Payment Charge is now inAUTHENTICATION_PENDING and requires consumer action.

Use the returned authenticationMethods to enable the consumer to review the login to their account, review the details, and approve the payment.

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:

If it is an in-browser experience, redirect the consumer to therequestUrl value.
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. Confirm authorization

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"
        }
    }
}

📘

💡Sandbox vs. Live APIs

1. Initialize a payment

Example request for a MOCK one-time payment

Response:

2. Authenticate the payment

3. Confirm authorization

Response:

4. Capture a payment

Response:

5. Refund a payment

💡
Sandbox vs. Live APIs