Installation

pip install

Install the latest SDK using pip:

pip install ping-sdk

Import

from ping.payments_api import PaymentsApi

Ping PaymentsApi Client

The PaymentsApiclient class acts as a factory for the Ping Payments API resource endpoints and holds the configuration of the Ping Payments API.

Initializing the client with a valid Tenant Id and an appropriate environment.

For testing use the Sandbox environment environment = "sandbox".
For Production use environment = "production".

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555', #tenant_id given py ping
  environment = 'sandbox' #"sandox" for testing, "production" for production usage.
)

Verify the connection

Use the Ping endpont to verify the connection to the API.

Merchant (Endpoint)

The merchant endpoint exposes several functions dedicated to dealing with merchant objects. A merchant is some party, an organization or juridicial entity that you wish, as an Tenant, to create a payment to.

Methods

List Merchants

Get an list of all the Merchant objects connected to a specific Tenant.

Usage:

Create a Ping Payments Api Client.
Call the list() function:
1. ```
payments_api.merchant.list()
```
Handle response

Returns

An object with a list of merchants for a Tenant, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)

result = payments_api.merchant.list()
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

[
  {
    "email": "[email protected]",
    "id": "55555555-5555-5555-5555-555555555555",
    "name": "Merchant A",
    "organization": {
      "country": "NO",
      "no_organization_number": "555555555"
    },
    "phone_number": "0731231234",
    "status": "APPROVED"
  },
  {
    "email": "[email protected]",
    "id": "55555555-5555-5555-5555-555555555555",
    "name": "Merchant B",
    "organization": {
      "country": "SE",
      "se_organization_number": "555555-5555"
    },
    "phone_number": "0705555555",
    "status": "CREATED"
  }
]

Create Merchant

Create and connect a new Merchant to a Tenant.

Usage

Create a Ping Payments Api Client.
Call the create() function with a merchant_object:
1. ```
payments_api.merchant.create(merchant_object);
```
Handle response

Parameters

Parameter	Type	Description
merchant_object	object	Object containing required parameters for creating a merchant

Returns

Id of the merchant that got created, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)

merchant_object = {
  "name": 'example-name',
  "organisation": {
    "country": 'SE',
    "se_organisation_number": '5555555555'
  }
}

result = payments_api.merchant.create(merchant_object)
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "id": "55555555-5555-5555-5555-555555555555"
}

Get Merchant

Get a specific Merchant connected to a Tenant.

Usage

Create a Ping Payments Api Client.
Call the get() function with a Merchant Id:
1. ```
payments_api.merchant.get(merchant_id);
```
Handle response

Parameters

Parameter	Type	Requierd	Description
merchant_id	string	Yes	Id of a specific merchant

Returns

Object of a merchant with the given Merchant Id, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)

merchant_id = "55555555-5555-5555-5555-555555555555"

result = payments_api.merchant.create(merchant_id)
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "email": "[email protected]",
  "id": "55555555-5555-5555-5555-555555555555",
  "name": "Merchant",
  "organization": {
    "country": "SE",
    "se_organization_number": "555555-5555"
  },
  "phone_number": "0705555555",
  "status": "APPROVED"
}

Payment Order (Endpoint)

A Payment Order is a container of all Payments pertaining to a single purchase. Each Tenant has its own list of Payment Orders.

Functions

List Payment Orders

Gets and returns a list of Payment Order objects for a Tenant.

Usage

Create a Ping Payments Api Client.
Call the list() function. You can can use an optional date range argument containing date_from and date_to values to limit the list of Payment Order objects returned, by date.
1. ```
payments_api.payment_order.list(date_from=None, date_to=None);
```
Handle response

Parameters:

Containing	Type	Required	Format	Description
date_from	string($date-time)	No	ISO 8601	Start date to find payouts in a date range
date_to	string($date-time)	No	ISO 8601	End date to find payouts in a date range

Returns

Object with a list of Payment Order objects for a Tenant, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)

result = payments_api.payment_order.list()
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

[
   {
      "created_at":"2021-11-05T10:04:19.275000Z",
      "currency":"SEK",
      "id":"55555555-5555-5555-5555-555555555555",
      "payments":[
         {
            "created_at":"2021-11-15T09:15:01.400000Z",
            "currency":"SEK",
            "id":"55555555-5555-5555-5555-555555555555",
            "payments":[
               {
                  "currency":"SEK",
                  "id":"55555555-5555-5555-5555-555555555555",
                  "metadata":{
                     
                  },
                  "method":"m_commerce",
                  "order_items":[
                     
                  ],
                  "provider":"swish",
                  "status":"INITIATED",
                  "status_history":[
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:00:33.714179Z",
                        "status":"INITIATED"
                     }
                  ]
               },
               {
                  "currency":"SEK",
                  "id":"55555555-5555-5555-5555-555555555555",
                  "metadata":{
                     
                  },
                  "method":"m_commerce",
                  "order_items":[
                     
                  ],
                  "provider":"swish",
                  "status":"ABORTED",
                  "status_history":[
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:00:33.714179Z",
                        "status":"INITIATED"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:32.714179Z",
                        "status":"ABORTED"
                     }
                  ]
               },
               {
                  "currency":"SEK",
                  "id":"55555555-5555-5555-5555-555555555555",
                  "metadata":{
                     
                  },
                  "method":"m_commerce",
                  "order_items":[
                     
                  ],
                  "provider":"swish",
                  "status":"COMPLETED",
                  "status_history":[
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:00:33.714179Z",
                        "status":"INITIATED"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:30.714179Z",
                        "status":"PENDING"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:32.714179Z",
                        "status":"COMPLETED"
                     }
                  ]
               },
               {
                  "currency":"SEK",
                  "id":"55555555-5555-5555-5555-555555555555",
                  "metadata":{
                     
                  },
                  "method":"m_commerce",
                  "order_items":[
                     
                  ],
                  "provider":"swish",
                  "status":"COMPLETED",
                  "status_history":[
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:00:33.714179Z",
                        "status":"INITIATED"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:30.714179Z",
                        "status":"PENDING"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:32.714179Z",
                        "status":"COMPLETED"
                     }
                  ]
               },
               {
                  "currency":"SEK",
                  "id":"55555555-5555-5555-5555-555555555555",
                  "metadata":{
                     
                  },
                  "method":"m_commerce",
                  "order_items":[
                     
                  ],
                  "provider":"swish",
                  "status":"ABORTED",
                  "status_history":[
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:00:33.714179Z",
                        "status":"INITIATED"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:30.714179Z",
                        "status":"PENDING"
                     },
                     {
                        "details":null,
                        "occurred_at":"2022-06-15T12:01:32.714179Z",
                        "status":"ABORTED"
                     }
                  ]
               }
            ],
            "status":"OPEN"
         }
      ]

Create Payment Order

Creates a new Payment Order connected to a Split Tree datastructure.

Usage

Create a Ping Payments Api Client.
Call the create() function with a request containging some parameters:
1. ```
payments_api.payment_order.create(split_tree_id, currency);
```
Handle response

Parameters

Parameter	Type	Required	Description
split_tree_id	string	Yes	String containing the ID of a specific split tree
currency	string	Yes	Enum: `SEK`, `NOK` Type of currency used for this payment order. Payments connected to a payment order must have the same currency as the payment order

Returns

Object containing a Payment Order Id of the created Payment Order, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
split_tree_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.create(split_tree_id, "SEK")
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "id": "55555555-5555-5555-5555-555555555555"
}

Get Payment Order

Gets a specific Payment Order associated with a Tenant.

Usage

Create a Ping Payments Api Client.

Call the get() function with a Payment Order Id:

payments_api.payment_order.get(payment_order_id);

Handle response

Paramaters:

Parameter	Type	Required	Description
payment_order_id	string	Yes	Id of a specific payment Order

Returns

A Payment Order object, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
payment_order_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.get(payment_order_id)
if result.is_success():
    print(result.body)
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "created_at": "2021-11-15T09:15:01.400000Z",
  "currency": "SEK",
  "id": "55555555-5555-5555-5555-555555555555",
  "payments": [
    {
      "currency": "SEK",
      "id": "55555555-5555-5555-5555-555555555555",
      "metadata": {},
      "method": "m_commerce",
      "order_items": [],
      "provider": "swish",
      "status": "INITIATED",
      "status_history": [
        {
          "at": "2022-06-15T12:00:33.714179Z",
          "details": null,
          "status": "INITIATED"
        }
      ]
    },
    {
      "currency": "SEK",
      "id": "55555555-5555-5555-5555-555555555555",
      "metadata": {},
      "method": "m_commerce",
      "order_items": [],
      "provider": "swish",
      "status": "COMPLETED",
      "status_history": [
        {
          "at": "2022-06-15T12:00:33.714179Z",
          "details": null,
          "status": "INITIATED"
        },
        {
          "at": "2022-06-15T12:01:32.714179Z",
          "details": null,
          "status": "PENDING"
        },
        {
          "at": "2022-06-15T12:03:33.714179Z",
          "details": null,
          "status": "COMPLETED"
        }
      ]
    },
    {
      "currency": "SEK",
      "id": "55555555-5555-5555-5555-555555555555",
      "metadata": {},
      "method": "m_commerce",
      "order_items": [
        {
          "amount": 850,
          "merchant_id": "55555555-5555-5555-5555-555555555555",
          "name": "Utkörning, Pizza",
          "vat_rate": 12
        }
      ],
      "provider": "swish",
      "status": "PENDING",
      "status_history": [
        {
          "details": null,
          "occurred_at": "2022-06-15T12:00:33.714179Z",
          "status": "INITIATED"
        },
        {
          "details": null,
          "occurred_at": "2022-06-15T12:01:32.714179Z",
          "status": "PENDING"
        }
      ]
    }
  ],
  "status": "OPEN"
}

Update Payment Order

Updates a Payment Order with a new Split Tree Id and potentional related parameters.

Usage

Create a Ping Payments Api Client.
Call the update() function with a Payment Order Id, Split Tree Id and opptional splitParameters:
1. ```
payments_api.payment_order.update(payment_order_id, split_tree_id);
```
Handle response

Parameters:

Parameter	Type	Required	Description
payment_order_id	string	Yes	Id of a specific Payment Order
split_tree_id	string	Yes	Id of the new Split Tree to be used.

Returns

Returns an empty response, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
payment_order_id = '55555555-5555-5555-5555-555555555555'
split_tree_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.get(payment_order_id, split_tree_id)
if result.is_success():
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

204 No content

{}

Closed Payment Order

Closes a Payment Order. No further Payments can be added to the Payment Order. Refunds are still possible at this stage.

Usage

Create a Ping Payments Api Client.

Call the close() function with a Payment Order Id:

payments_api.payment_order.close(payment_order_id);

Handle response

Parameters:

Parameter	Type	Required	Description
payment_order_id	string	Yes	Id of a specific payment order

Returns

Returns an empty response, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
payment_order_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.close(payment_order_id)
if result.is_success():
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

204 No content

{}

Split Payment Order

Splits a Payment Order according to its Split Tree. Partial refunds are possible at this stage.

Usage

Create a Ping Payments Api Client.

Call the split() function with a Payment Order Id:

payments_api.payment_order.split(payment_order_id, fast_forward=false);

Handle response

Parameters:

Parameter	Type	Required	Description
payment_order_id	string	Yes	ID of a specific payment order
fast_forward	boolean	No	Boolean that indicates that a payment order shall be closed and split. Default: `false`

Returns

Returns an empty response, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
payment_order_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.split(payment_order_id)
if result.is_success():
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

204 No content

{}

Settle Payment Order

Splits a Payment Order according to its Split Tree. Partial refunds are possible at this stage.

Usage

Create a Ping Payments Api Client.

Call the settle() function with a Payment Order Id:

payments_api.payment_order.settle(payment_order_id, fast_forward=false);

Handle response

Parameters:

Parameter	Type	Required	Description
payment_order_id	string	Yes	Id of a specific payment order
fast_forward	boolean	No	Boolean that indicates that a payment order shall be closed and split. Default: `false`

Returns

Returns an empty response, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

payments_api = PaymentsApi(
  tenant_id = '55555555-5555-5555-5555-555555555555',
  environment = 'sandbox'
)
payment_order_id = '55555555-5555-5555-5555-555555555555'

result = payments_api.payment_order.settle(payment_order_id)
if result.is_success():
    # successful code
elif result.is_error():
    print(result.errors)
    # error code

Response

204 No content

{}

Payment (Endpoint)

The Payment endpoint exposes two functions dedicated to dealing with Payments.

Functions

Initiate
Get

Initiate Payment

Initiates new Payment.

Usage

Create a Ping Payments Api Client.
Call the initiate() function with a Payment Order Id and payment_object:
1. ```
payments_api.payment.initiate(payment_order_id, payment_object); 
```
Handle response

Parameters

Parameter	Type	Required	Description
payment_object	payment_object	Yes	Request body
payment_order_id	string	Yes	Id of a payment Order

Returns

An payment Object , or an error response.

Callback

A payment goes through different stages after being initiated.

The payment status starts as INITIATED, continues as PENDING and last becomes either COMPLETED, DECLINED, ABORTED, EXPIRED or CRASHED.

Example Usage

from ping.payments_api import PaymentsApi

  payments_api = PaymentsApi(
    tenant_id = '55555555-5555-5555-5555-555555555555',
    environment = 'sandbox'
  )
  payment_order_id = "55555555-5555-5555-5555-555555555555"

  payment_object = {
    "currency": "SEK",
    "metadata": {
      "delivery_id": "368745"
    },
    "total_amount": 9400,
    "method": "e_commerce",
    "order_items": [
      {
        "amount": 2500,
        "merchant_id": "55555555-5555-5555-5555-555555555555",
        "name": "Delivery, Pasta (Pasta Place)",
        "vat_rate": 12
      },
      {
        "amount": 6900,
        "merchant_id": "55555555-5555-5555-5555-555555555555",
        "name": "Pasta (Pasta Place)",
        "vat_rate": 12
      }
    ],
    "provider": "swish",
    "provider_method_parameters": {
      "message": "Pasta from Pasta Place",
      "phone_number": "0700000000"
    },
    "status_callback_url": "https://somesite.com/callback"
  }

  result = payments_api.payment.initiate(payment_object, payment_order_id)
  
	if result.is_success():
    print(result.body)
  	# successful code
	elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "id":"55555555-5555-5555-5555-555555555555",
  "provider_method_response": {
    "payment_request_token": "-P3RvSYrQQqNFhY3lyFgBy6hCg1qFGdz",
    "qr_code": null,
    "swish_url": "swish://paymentrequest?token=c28a4061470f4af48973bd2a4642b4fa&callbackurl=merchant%253A%252F%252F"
  }
}

Get Payment

Get a specific Payment.

Usage

Create a Ping Payments Api Client.
Call the get() function with an Payment Order Id and Payment Id:
1. ```
payments_api.payment.get(payment_order_id, payment_id); 
```
Handle response

Parameters

Parameter	Type	Required	Description
payment_id	string	Yes	Id of a payment
payment_order_id	string	Yes	Id of a payment order

Returns

A Payment object , or an error response.

Example Usage

from ping.payments_api import PaymentsApi

  payments_api = PaymentsApi(
    tenant_id = '55555555-5555-5555-5555-555555555555',
    environment = 'sandbox'
  )
  payment_order_id = "55555555-5555-5555-5555-555555555555"
	payment_id = "55555555-5555-5555-5555-555555555555"

  result = payments_api.payment.get(payment_order_id, payment_id)
  
	if result.is_success():
    print(result.body)
  	# successful code
	elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "currency": "SEK",
  "id": "55555555-5555-5555-5555-555555555555",
  "metadata": {
    "delivery_id": "230955"
  },
  "method": "e_commerce",
  "order_items": [
    {
      "amount": 850,
      "merchant_id": "55555555-5555-5555-5555-555555555555",
      "name": "Utkörning, Pizza",
      "vat_rate": 12
    }
  ],
  "provider": "swish",
  "status": "DECLINED",
  "status_history": [
    {
      "details": null,
      "occurred_at": "2022-06-15T12:00:33.714179Z",
      "status": "INITIATED"
    },
    {
      "details": null,
      "occurred_at": "2022-06-15T12:01:32.714179Z",
      "status": "PENDING"
    },
    {
      "details": {
        "provider_data": {
          "errorCode": "RF07",
          "errorReason": "Transaction declined"
        }
      },
      "occurred_at": "2022-06-15T12:03:33.714179Z",
      "status": "DECLINED"
    }
  ]
}

Payout (Endpoint)

The Payout endpoint exposes two methods dedicated to dealing with fetching of payouts.

Functions

List
Get

List Payouts

Lists all payouts for a Tenant.

Usage

Create a Ping Payments Api Client.

Call the list() function:

payments_api.payout.list(date_from=None, date_to=None);

Handle response

Parameters

Containing	Type	Required	Format	Description
date_from	string($date-time)	No	ISO 8601	Start date to find payouts in a date range
date_to	string($date-time)	No	ISO 8601	End date to find payouts in a date range

Returns

Array of payout objects, or an error response.

Example Usage

from ping.payments_api import PaymentsApi

  payments_api = PaymentsApi(
    tenant_id = '55555555-5555-5555-5555-555555555555',
    environment = 'sandbox'
  )

  result = payments_api.payout.list()
  
	if result.is_success():
    print(result.body)
  	# successful code
	elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

[
  {
    "amount": 0,
    "completed_at": "string",
    "currency": "SEK",
    "id": "55555555-5555-5555-5555-555555555555"
  }
]

Get Payout

Get a specific Payout.

Usage

Create a Ping Payments Api Client
Call the get() function with an Payout Id
1. ```
payments_api.payment.get(payout_id); 
```
Handle response

Parameters

Parameter	Type	Required	Description
payout_id	string	Yes	Id of a specific payout

Returns

A Payout object , or an error response.

Example Usage

from ping.payments_api import PaymentsApi

  payments_api = PaymentsApi(
    tenant_id = '55555555-5555-5555-5555-555555555555',
    environment = 'sandbox'
  )
  payout_id = "55555555-5555-5555-5555-555555555555"

  result = payments_api.payout.get(payout_id)
  
	if result.is_success():
    print(result.body)
  	# successful code
	elif result.is_error():
    print(result.errors)
    # error code

Response

200 OK

{
  "amount": 0,
  "completed_at": "string",
  "currency": "SEK",
  "id": "55555555-5555-5555-5555-555555555555"
}