Skip to content

_splits_en.html.md

Latest commit

 

History

History
453 lines (411 loc) · 12.9 KB

_splits_en.html.md

File metadata and controls

453 lines (411 loc) · 12.9 KB
Raw

Split Payments {#payments_split}

Split payments is a solution developed for marketplaces. Split payments provides a way to pay multiple service providers, making one charging operation from the customer's card.

To connect to split payments, contact your manager in QIWI Support and request access to the solution.

Integration with QIWI Payment form {#use-splits-qiwi-form}

To send split payments, send in API request Invoice a JSON-array
splits with merchants data.

Data format {#form-split-json}

Example of invoice request with split payments

curl --location \
  --request PUT \
  'https://api.qiwi.com/partner/payin/v1/sites/Obuc-02/bills/eqwptt' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
    "amount": {
        "value": "3.00",
        "currency": "RUB"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "comment": "My comment",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "value": 2.00,
                "currency": "RUB"
            },
            "orderId": "dressesforwhite",
            "comment": "Some purchase 1"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "value": 1.00,
                "currency": "RUB"
            },
            "orderId": "shoesforvalya",
            "comment": "Some purchase 2"
        }
    ]
}'

Response example with invoice and split payments

{
    "billId": "eqwptt",
    "invoiceUid": "44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "amount": {
        "currency": "RUB",
        "value": "3.00"
    },
    "expirationDateTime": "2021-12-31T23:59:59+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2021-02-05T10:21:17+03:00"
    },
    "comment": "My comment",
    "flags": [
        "TEST"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=44b2ef2a-edc6-4aed-87d3-01cf37ed2732",
    "splits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-00",
            "splitAmount": {
                "currency": "RUB",
                "value": "2.00"
            },
            "orderId": "dressesforwhite",
            "comment": "Some purchase 1"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "Obuc-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "1.00"
            },
            "orderId": "shoesforvalya",
            "comment": "Some purchase 2"
        }
    ]
}

JSON-array splits format:

Name Type Description
splits Array Merchants data array
----- ------ ------
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Merchant ID
splitAmount Object Merchant reimbursement data
---- ---- -----
value Number Amount of reimbursement rounded down to two decimals
currency String(3) Text code of reimbursement currency, by ISO. Only RUB value
----- ----- -----
orderId String Order number (optional)
comment String Comment for the order (optional)
The amount of reimbursements to merchants should be equal to the amount charged from the customer's card.

In JSON-object splits of the response the data on split payments are present:

Response field Type Description
splits Array Array with split payments data
----- ------ ------
type String Data type. Always MERCHANT_DETAILS
siteUid String Merchant ID
splitAmount Object Merchant reimbursement data
---- ---- -----
value String Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO
----- ----- -----
orderId String Order number
comment String Comment for the order

Integration with Merchant's form {#use-splits-merchant-form}

To send split payment, send in API request Payment a JSON-array
paymentSplits with merchants data.

Data format {#pay-split-json}

{
 "paymentMethod": "...",
 "customer": "....",
 "deviceData": "...",
 "paymentSplits": [
   {
     "type":"MERCHANT_DETAILS",
     "siteUid":"shop_mst-01",
     "splitAmount": {
       "value":300.00,
       "currency":"RUB"
     },
     "orderId":"dasdad444ll4ll",
     "comment":"Flowers"
  },
  {
    "type":"MERCHANT_DETAILS",
    "siteUid":"shop_mst-02",
    "splitAmount": {
      "value":200.00,
      "currency":"RUB"
      },
      "orderId":"sdadada887sdDDDDd",
      "comment":"Watermelon"
    }
  ]
}

Response with split payments

{
   "paymentId": "23",
   "billId": "autogenerated-2a8fcfab-45cb-43b9-81bd-edf65e0ef874",
   "createdDateTime": "2020-10-12T15:29:12+03:00",
   "amount": {
   "currency": "RUB",
   "value": "100.00"
},
   "capturedAmount": {
   "currency": "RUB",
   "value": "100.00"
},
   "refundedAmount": {
   "currency": "RUB",
   "value": "0.00"
},
   "paymentMethod": "..",
   "status": "..",
   "paymentCardInfo": "..",
   "paymentSplits": [
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-01",
          "splitAmount": {
            "currency": "RUB",
            "value": "30.00"
          },
          "splitCommissions": {
            "merchantCms": {
              "currency": "RUB",
              "value": "10.00"
            }
          },
          "orderId": "313fh1f23j13k1k",
          "comment": "Some goods"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-02",
          "splitAmount": {
             "currency": "RUB",
             "value": "20.00"
           },
          "splitCommissions": {
              "merchantCms": {
                "currency": "RUB",
                "value": "10.00"
              }
            },
          "orderId": "sdadada887sdDDDDd",
          "comment": "Watermelon"
       },
       {
          "type": "MERCHANT_DETAILS",
          "siteUid": "shop_mst-03",
          "splitAmount": {
            "currency": "RUB",
            "value": "50.00"
          },
          "splitCommissions": {
            "merchantCms": {
              "currency": "RUB",
              "value": "10.00"
            }
          },
          "orderId": "dasdad444ll4ll",
          "comment": "Flowers"
       }
    ]
}

JSON-array paymentSplits format:

Name Type Description
paymentSplits Array Merchants data array
----- ------ ------
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Merchant ID
splitAmount Object Merchant reimbursement data
---- ---- -----
value Number Amount of reimbursement rounded down to two decimals
currency String(3) Text code of reimbursement currency, by ISO. Only RUB value
----- ----- -----
orderId String Order number (optional)
comment String Comment for the order (optional)
The amount of reimbursements to merchants should be equal to the amount charged from the customer's card.

In JSON-object paymentSplits of the response the data on split payments and commissions are present:

Response field Type Description
paymentSplits Array Array with split payments data
----- ------ ------
type String Data type. Always MERCHANT_DETAILS
siteUid String Merchant ID
splitAmount Object Merchant reimbursement data
---- ---- -----
value String Amount of reimbursement
currency String(3) Text code of reimbursement currency, by ISO
----- ----- -----
splitCommissions Object Commission data (optional)
----- ---- -----
merchantCms Object Commission from the merchant
---- ----- ----
value String Amount of the commission
currency String(3) Text code of the commission currency, by ISO
----- ----- -----
orderId String Order number
comment String Comment for the order

Refunds on split payments {#split-refund}

After a successful authorization of the card charging, a refund is available for the split payment transaction. Both partial and complete refunds are supported.

Example of refund request

PUT /partner/payin/v1/sites/test-01/payments/23/refunds/1 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "refundSplits": [
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-01",
    "splitAmount": {
      "value": 30.00,
      "currency": "RUB"
    },
    "orderId": "sdadada887sdDDDDd",
    "comment": "Watermelon"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-02",
    "splitAmount": {
      "value": 20.00,
      "currency": "RUB"
    },
   
    "orderId": "313fh1f23j13k1k",
    "comment": "Some goods"
  },
  {
    "type": "MERCHANT_DETAILS",
    "siteUid": "shop_mst-03",
    "splitAmount": {
      "value": 50.00,
      "currency": "RUB"
    },
    "orderId": "dasdad444ll4ll",
    "comment": "Flowers"
  }
  ]
}

Example of response

{
    "refundId": "1",
    "createdDateTime": "2020-10-12T15:32:29+03:00",
    "amount": {
        "currency": "RUB",
        "value": "100.00"
    },
    "status": {
        "value": "COMPLETED",
        "changedDateTime": "2020-10-12T15:32:30+03:00"
    },
    "refundSplits": [
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-02",
            "splitAmount": {
                "currency": "RUB",
                "value": "20.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "sdadada887sdDDDDd",
            "comment": "Watermelon"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-01",
            "splitAmount": {
                "currency": "RUB",
                "value": "30.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "313fh1f23j13k1k",
            "comment": "Some goods"
        },
        {
            "type": "MERCHANT_DETAILS",
            "siteUid": "shop_mst-03",
            "splitAmount": {
                "currency": "RUB",
                "value": "50.00"
            },
            "splitCommissions": {
                "merchantCms": {
                    "currency": "RUB",
                    "value": "10.00"
                }
            },
            "orderId": "dasdad444ll4ll",
            "comment": "Flowers"
        }
    ]
}

To send split payments refund, send in API request Refund a JSON-array
refundSplits with refunds information. Put the total amount of the refund and the refund amount for each split.

The amount of cancelled reimbursements to merchants should be equal to the total amount of the refund.

JSON-array refundSplits format:

Name Type Description
refundSplits Array Merchants refunds data array
----- ------ ------
type String Data type. Always MERCHANT_DETAILS (merchant details)
siteUid String Merchant ID
splitAmount Object Merchant cancelled reimbursement data
---- ---- -----
value Number Amount of cancelled reimbursement
currency String(3) Text code of cancelled reimbursement currency, by ISO. Only RUB value
----- ----- -----
orderId String Order number (optional)
comment String Comment for the order (optional)

In JSON-object refundSplits of the response the data on accepted refunds are present:

Response field Type Description
refundSplits Array Array with refunds data
----- ------ ------
type String Data type. Always MERCHANT_DETAILS
siteUid String Registered merchant ID
splitAmount Object Merchant cancelled reimbursement data
---- ---- -----
value String Amount of cancelled reimbursement
currency String(3) Text code of cancelled reimbursement currency, by ISO
----- ----- -----
splitCommissions Object Commission data (optional)
----- ---- -----
merchantCms Object Commission from the merchant
---- ----- ----
value String Amount of the commission
currency String(3) Text code of the commission currency, by ISO
----- ----- -----
orderId String Order number
comment String Comment for the order

Notifications on split payments and refunds {#split-operations-notification}

Notifications for split payments and split payment refunds are formed similarly to the API requests described above: