Skip to main content

Accept Payments

With our low-code, hosted payment solution you can offer an optimal payment experience, customized for your brand, with minimal integration effort or complexity.

This guide covers the high level payment flow and how you can integrate payments into your products and services. Payment method specific flows will be covered in their respective sections.

Before you start​

To interact with our Payment APIs you must obtain an access token using the API credentials provided to you during your onboarding process. You will have at least one set of credentials per environment (Sandbox and Live). More details can be found in our Getting Started guide.

Payment Flow​

The diagram below illustrates the high-level payment flow:

sequenceDiagram participant eu as Customer participant p as Your Platform participant hpp as GetPaid HPP participant papi as GetPaid Payments API participant auth as GetPaid Auth Server eu ->> p: 1. Pay p ->> auth: 2. Authenticate auth ->> p: Access Token p ->> papi: 3. Initiate Payment papi ->> p: HPP Link p ->> eu: 4. Redirect to HPP link eu ->> hpp: 5. Provide Payment Method and confirm hpp ->> papi: 6. Process Payment papi ->> hpp: Payment Result hpp ->> eu: 7. Redirect to Platform p ->> papi: 8. Get Payment Status p ->> eu: 9. Show success or failure page papi -->> p: 10. Payment Webhook

Steps​

  1. The customer (end-user) chooses to make a payment via your platform
  2. You obtain an OAuth access token from our Authorization Server using your previously supplied credentials (see Getting Started)
  3. You Initiate a Payment providing the amount, currency and optionally merchant(s) as well as your redirect and webhook URLs
  4. Using the link returned in the Initiate Payment API response, you redirect the customer to our Hosted Payment Page (HPP)
  5. The customer chooses their preferred payment method and supplies their details
  6. We process the payment. This may involve multiple interactions between the HPP and customer if further authentication is required e.g. 3D-Secure
  7. The HPP redirects the customer back to the URL you provided during Initiation
  8. (Optional) Using the gp_payment query parameter appended to your redirect URL you can retrieve the status of the Payment via our API
  9. Show a payment confirmation page
  10. Handle the payment_succeeded or payment_failed webhooks as final confirmation of payment
tip

Due to the asynchronous nature of some payment flows, we recommend waiting for final confirmation via webhook before you fulfil orders in your system.

Payment Initiation​

To start the payment flow you must initiate a payment. Here you provide the amount and currency of the payment, the merchant(s) you are facilitating the payment for, if any, and your integration URLs.

tip

For a comprehensive reference on the available parameters, please see our API Reference.

POST https://api.sandbox.getpaid.io/payments

Sample request​

curl -X POST \
  https://api.sandbox.getpaid.io/payments \
  -H 'authorization: Bearer {{your_access_token}}' \
  -H 'content-type: application/json' \
  -d '{
    "amount_minor":1000,
    "currency":"EUR",
    "payment_method":{
      "type":"user_selected"
    },
    "reference":"ORD-123456",
    "description":"Your Haircutz appointment at Emma Stone Hair Salon",
    "integration":{
      "type":"hosted",
      "generate_qr_code":true
    },
    "routing":{
      "platform":{
        "amount_minor":100,
        "processing_fee_contribution":50
      },
      "merchants":[
        {
          "type":"seller",
          "id":"acc_4zjjxn0nm1tnweqbttedkvnsc8",
          "reference":"ORD-123456",
          "amount_minor":900,
          "processing_fee_contribution":50
        }
      ]
    },
    "urls":{
      "redirect":"https://haircutz.co/checkout/complete?order_id=ORD-123456",
      "webhook":"https://webhooks.haircutz.co/getpaid"
    },
    "cit_mode":"one_off"
  }'

Sample response​

{
  "id": "pay_4fyeqdchy8vka1m6407t74kfdw",
  "status": "initiated",
  "reference": "ORD-123456",
  "expires_at": "2023-01-31T11:26:35.2349671Z",
  "_links": {
    "curies": [
      {
        "name": "gp",
        "href": "https://api.getpaid.io/rels/{rel}",
        "templated": true
      }
    ],
    "gp:redirect": {
      "href": "https://hpp.sandbox.getpaid.io/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "methods": ["GET"]
    },
    "self": {
      "href": "https://api.sandbox.getpaid.io/payments/pay_4fyeqdchy8vka1m6407t74kfdw",
      "methods": ["GET"]
    }
  }
}

Redirecting the customer​

In order for the customer to process the payment you should redirect them to the gp:redirect link included in the Initiate Payment API response. This is a one-time link tied to a specific payment.

Routing payments​

When initiating a payment you (as platform) can determine the funds that should be routed to the platform as well as to one or more merchants. Each merchant specified must have been onboarded and activated. In addition, you can configure the processing fee contribution charged to each actor.

Routing rules​

  1. If routing field is not provided, all the funds (minus the processing fee) will be routed to the platform.
  2. If routing field is provided:
    • There must be exactly one route for merchant of type seller.
    • The sum of the platform's and merchants' amount_minor declared at the routing should have the same value as the total amount_minor of the payment.
    • The sum of the platform's and merchants' processing_fee_contribution declared at the routing must sum 100.
    • The amount_minor for each actor cannot be lower than his proportional processing fee configured at the routing.

Let's suppose a Payment of 50 EUR, and the platform's processing_fee_contribution is 100. This means that getpaid will deduct the total processing fee from the platform.

Then, if the configured platform's amount_minor is 0 EUR, the processing fee could not be deducted and the payment cannot be initiated.

Example 1: Only platform. Processing Fee deducted to the platform​

{
  "amount_minor": 1000,
  "currency": "EUR",
  // other fields redacted
}

In this example, the whole amount of the payment will be routed to the platform, and the processing fee would be charged to it:

PartyAmount
Platform10.00 EUR (minus 100% of processing fee)

Example 2: Single merchant, no commission for the platform. Processing Fee deducted to the merchant​

{
  "amount_minor": 1000,
  "currency": "EUR",
  "routing": {
    "platform": {
      "amount_minor": 0,
      "processing_fee_contribution": 0
    },
    "merchants": [
      {
        "type": "seller",
        "id": "acc_4t2942vvcaj9h41mcpaqwss7dp",
        "amount_minor": 1000,
        "processing_fee_contribution": 100
      }
    ]
  },
  // other fields redacted
}

In this example, the whole amount of the payment will be routed to the merchant, and the processing fee would be charged to him:

PartyAmount
Platform0.00 EUR
Merchant 110.00 EUR (minus 100% of processing fee)

Example 3: Multiple merchants, no commission for the Platform. Processing Fee distributed between merchants​

{
  "amount_minor": 1000,
  "currency": "EUR",
  "routing": {
    "platform": {
      "amount_minor": 0,
      "processing_fee_contribution": 0
    },
    "merchants": [
      {
        "type": "seller",
        "id": "acc_4t2942vvcaj9h41mcpaqwss7dp",
        "amount_minor": 900,
        "processing_fee_contribution": 70
      },
      {
        "type": "merchant",
        "id": "acc_5y21q8rteks0q12puorlgjd1pq",
        "amount_minor": 100,
        "processing_fee_contribution": 30
      }
    ]
  },
  // other fields redacted
}

In this example, the payment is split across the merchants, and the processing fee would be charged according to the split indicated in the request:

PartyAmount
Platform0.00 EUR
Merchant 19.00 EUR (minus 70% of processing fee)
Merchant 21.00 EUR (minus 30% of processing fee)

Example 4: Multiple merchants, commission for the Platform. Processing Fee distributed between merchants and platform​

{
  "amount_minor": 1000,
  "currency": "EUR",
  "routing": {
    "platform": {
      "amount_minor": 100,
      "processing_fee_contribution": 10
    },
    "merchants": [
      {
        "type": "seller",
        "id": "acc_4t2942vvcaj9h41mcpaqwss7dp",
        "amount_minor": 800,
        "processing_fee_contribution": 70
      },
      {
        "type": "merchant",
        "id": "acc_5y21q8rteks0q12puorlgjd1pq",
        "amount_minor": 100,
        "processing_fee_contribution": 20
      }
    ]
  },
  // other fields redacted
}

In this example, the payment is split across the merchants and the platform, and the processing fee would be charged according to the split indicated in the request:

PartyAmount
Platform1.00 EUR (minus 10% of processing fee)
Merchant 18.00 EUR (minus 70% of processing fee)
Merchant 21.00 EUR (minus 20% of processing fee)

Strong Customer Authentication (SCA) / 3D-Secure​

In some cases, the customer may need to authenticate with the relevant payment institution using Strong Customer Authentication, for example, 3D-Secure. The Hosted Payment Page will automatically handle these cases on your behalf, directing the customer through the authentication flow before returning them to your target redirect URL upon completion.

In these flows, where the payment outcome tends to be asynchronous we recommend using webhooks to determine the status of the payment as the redirect of the customer may not always be guaranteed (network issues etc.).

Payment status​

info

The payment status is not updated via a webhook, a payment status can be retrieved from the status field in the Get Payment call

initiated​

The payment has been initiated by the platform/merchant and is pending further input to complete the payment.

started​

The payment process has been formally initiated and the necessary information has been collected.

authenticating​

The payment was submitted for processing but requires further authentication (e.g. 3D-Secure) to complete.

authenticated​

The payment has been authenticated. The legitimacy of the payment information has been confirmed and the payment can proceed to the next stages.

authentication_failed​

The end-user failed to authenticate.

authorized​

The payment has been authorized (funds reserved) by the issuer/provider.

declined​

The payment has failed to be completed. This could be due to insufficient funds, an issue with the payment source, or other reasons that prevent the payment from being processed.

processing​

The payment is currently being processed, this status indicates that the transaction is in progress.

captured​

The payment funds have been captured and submitted for clearing/settlement.

not_completed​

The payment process was initiated but did not reach completion.

settled​

The payment has been successfully processed and the funds have been transferred to the payee's account. The transaction is considered complete and the amount is settled.

refund_initiated​

A refund process has been initiated for a previous payment. The payer will receive their money back through this refund process.

refund_completed​

The refund process has been successfully completed, and the funds have been returned to the payer. The refund transaction is finalized.

Settlement and pay-outs​

After a payment is authorized and captured it will be cleared and eventually settled. We will then execute payouts, applying the routing rules specified in the payment initiation request.