The payment_links endpoint supports several methods.

Get: Fetch all payment_links created by tenant

/api/v1/payment_links

Header

Parameter	Type	Description
`tenant_id`	`string`	The ID given to a tenant by Ping Payments

200

A successful call. A list of payment links

[
   {
      "checkout_url": "string",
      "customer": {},
      "delivery_address": {},
      "distributed_by_email": true,
      "due_date": "string",
      "invoice_address": {
       "city": "string",
       "street_address": "string",
       "zip": "string"
   },
   "invoice_created": true,
   "items": [
      {   }
   ],
      "language": "SE",
      "logo_image_link": "string",
      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
      "merchant_name": "568614df-bf9e-4952-80ed-77fbb6c525f4",
      "ocr": "string",
      "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",
      "payment_link_id": "b299d88a-1d8a-4d54-8352-aa90479aab46",
      "payment_link_status_callback_url": "string",
      "payment_order_id": "a3710107-26e5-434c-8c5b-ebc19a77f372",
      "sms_status": "DELIVERED",
      "status": "CREATED",
      "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
      "total_amount": 0
   }
]

422

A validation error. The response contains a list of error objects.

{
  "errors": [
    {
      "description": "null value where string expected",
      "error": "null_value",
      "property": "open_banking.success_url"
    }
  ]
}

Post: Create a Payment Link

/api/v1/payment_links

Header

Parameter	Type	Description
`tenant_id`	`string`	The ID given to a tenant by Ping Payments

Payload

{
    "customer": {
      "email": "[email protected]",
      "first_name": "Bertil",
      "last_name": "Jönsson",
      "phone": "0700000000"
    },
    "delivery_address": {
      "city": "Örebro",
      "street_address": "Nygatan 15",
      "zip": "702 10"
    },
    "due_date": "2022-03-25",
    "invoice_address": {
      "city": "Örebro",
      "street_address": "Nygatan 15",
      "zip": "702 10"
    },
    "items": [
      {
        "description": "Hawaii Pizza",
        "price": 7000,
        "quantity": 2,
        "vat": 0.12
      }
    ],
    "language": "SE",
    "logo_image_link": "https://someurl.com/some-image.png",
    "merchant_id": "122da843-346e-4693-a7ef-985b8444156b",
    "payment_link_status_callback_url": "https://someurl.com/payment_link_callback",
    "payment_order_id": "122da843-346e-4693-a7ef-985b8444156b",
    "payment_provider_methods": [
      {
        "method": "mobile",
        "parameters": {
          "swish_message": "Tack för din betalning"
        },
        "provider": "swish"
      },
      {
        "method": "card",
        "provider": "verifone"
      }
    ],
    "supplier": {
      "city": "Örebro",
      "organization_number": "5555555555",
      "website": "https://somewebsite.com",
      "zip": "45133"
    },
    "total_amount": 14000
}

200

A successful call. The response contains a check_url and the id of the payment link that was just created.

{
    "checkout_url": "string",
    "id": "string"
}

422

{
  "errors": [
    {
      "description": "null value where string expected",
      "error": "null_value",
      "property": "open_banking.success_url"
    }
  ]
}

Get: Fetch a full representation of a payment_link

Put: Cancel a payment_link

Put: Distribute a payment_link

Get: Fetch a payment_link invoice

Put: Create an "invoice" based on a payment_link

Get: https://docs.pingpayments.com/payment_links_api_ref/#operation/GetPaymentLinkReceipt

From Github:

title Payment Links flow

participant tenant

actor user

participant checkout participant payment_links participant midas

tenant->midas:Create payment order (POST) /api/v1/payments_orders tenant<<--midas:OK (payment_order_id)

create payment_links tenant->payment_links:Create payment link (POST) /api/v1/payment_links

tenant<<--payment_links:OK (payment_link_id) tenant->payment_links:Distribute by sms (PUT) /api/v1/payment_links/distribute tenant<<--payment_links:OK

create user

user(1)<-payment_links:Sms with link to checkout

create checkout

user->checkout:Opens checkout url payment_links<-checkout:Fetch payment link\n(GET) /api/v1/payment_links/@payment_link_id

payment_links-->>checkout:OK (payment_link) user<<--checkout:Displays GUI user->checkout:Clicks on pay

checkout->payment_links:Initiate payment\n(POST) /api/v1/payments_links/@payment_link_id/payments

payment_links->midas:Initiate payment\n(POST) /api/v1/payments_orders/@payment_order_id/payments payment_links<<--midas:OK (payment_id) checkout<<--payment_links:OK (payment_id)

note left of checkout: User pays

note right of midas: Payment provider\nnotifies status checkout<-midas:Callback with @payment_status checkout-->>midas:OK

payment_links(1)<-midas:Inform checkout about @payment_status with\n- payment_order_id\n- payment_id

destroysilent payment_links

group #2f2e7b @payment_status == COMPLETED #white user<-checkout:Visar kvitto end

group #2f2e7b @payment_status == DECLINED | CRASHED | CANCELLED #white user<-checkout:Shows error message note left of checkout: User can try to click pay again\nto retry the purchase end

destroysilent user destroysilent checkout

tenant->midas:Close payment_order (PUT) /api/v1/payment_orders/@payment_order_id/close tenant<<--midas:OK