Payments

Check a payment’s status.

A payment resource is created for /payments/authorize or /payments/charges. A payment resource refers to a specific purchase order and contains all linked transactions of any kind. It gives you a good overview of the payment status and corresponding transactions.

Get a payment

To retrieve a payment, either use the orderId specified during the authorization or charge call, or use the retrieved payment id from the API reference.

curl https://api.unzer.com/v1/payments/s-pay-1 \
  -u s-priv-xxxxxxxxxx:
  
curl https://api.unzer.com/v1/payments/merchant-order-1 \
  -u s-priv-xxxxxxxxxx:
GET https://api.unzer.com/v1/payments/merchant-order-1

{
    "id": "s-pay-1",
    "state": {
        "id": 3,
        "name": "partly"
    },
    "amount": {
        "total": "90.0000",
        "charged": "80.0000",
        "canceled": "50.0000",
        "remaining": "10.0000"
    }
  ...
}

Payment amounts

There are 4 types of amounts within the payment resource.

Name Description
total Represents the maximum amount for this order. Initially this is the authorized or the charged amount. This amount can only be reduced if cancel was called on an authorization.
charged Represents the amount of money transferred from the customer to the merchant.
canceled Represents the amount of money refunded by the merchant to the customer. Only charges can be refunded.
remaining Represents the difference between total and charged.

Payment state

The following states are possible:

Id State Description
0 pending Only an authorization transaction was called.
Or some additional actions are required. It is likely that the customer needs to be redirected to a third-party payment system to enter some data.
1 completed Done when total and charged are equal.
If a customer has transferred too much money and the merchant refunds the overpaid amount, the status is also complete.
2 canceled If you cancel the entire authorization, the total amount is reduced to 0 and the status is canceled.
If all charges are refunded, the status is also canceled.
3 partly The total amount is only partially charged.
4 payment review Payment must be checked. Customer may have overpaid.
5 chargeback A refund triggered by the customer.
6 Pay page initiated A payment page has been initiated.

Payment state flow:

HEID_PPT_Schaubilder_b10.png

Depending on the payment type, the payment flow status changes from new to outstanding or completed. Optionally, it can also be partially if not all transactions have been completed.

Complete Payment response

The response could look like this:

Example payment object

GET https://api.unzer.com/v1/payments/merchant-order-1

{
    "id": "s-pay-1",
    "state": {
        "id": 3,
        "name": "partly"
    },
    "amount": {
        "total": "90.0000",
        "charged": "80.0000",
        "canceled": "50.0000",
        "remaining": "10.0000"
    },
    "currency": "EUR",
    "orderId": "merchant-order-1",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-1",
        "basketId": "",
        "metadataId": "",
        "typeId": "s-crd-bltpvrcnqeq2"
    },
    "transactions": [
        {
            "date": "2018-09-24 18:01:02",
            "type": "authorize",
            "url": "https://api.unzer.com/v1/payments/s-pay-1/authorize/s-aut-1",
            "amount": "100.0000"
        },
        {
            "date": "2018-09-24 18:01:12",
            "type": "charge",
            "url": "https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-1",
            "amount": "50.0000"
        },
        {
            "date": "2018-09-24 18:01:15",
            "type": "charge",
            "url": "https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-2",
            "amount": "30.0000"
        },
        {
            "date": "2018-09-24 18:01:23",
            "type": "cancel-authorize",
            "url": "https://api.unzer.com/v1/payments/s-pay-1/authorize/s-aut-1/cancels/s-cnl-1",
            "amount": "10.0000"
        },
        {
            "date": "2018-09-24 18:02:20",
            "type": "cancel-charge",
            "url": "https://api.unzer.com/v1/payments/s-pay-1/charges/s-chg-1/cancels/s-cnl-1",
            "amount": "50.0000"
        }
    ]
}

Response structure

The response contains an overview of all amounts and a status of the payment. There is also a summary of all transactions and a list of related resources (for example, customer).

Name Format Description
id string Payment id
state object Current state of this payment
* pending (0)
* completed (1)
* canceled (2)
* partly (3)
* payment review (4)
* chargeback (5)
state.id int(1) ID of the current state
state.name string Name of the current state
amount string Summary of all amounts
amount.total string Initial amount reduced by cancellations during authorization
amount.charged string Already charged amount
amount.canceled string Refunded amount of all charges
amount.remaining string Difference between total and charged
currency string(3) ISO currency code: For a list of possible codes, see: Amounts and Currencies
orderId string(256) Order id of the merchant application. This id can also be used to get payments from the api. The id has to be unique for the used key pair.
invoiceId string(16) InvoiceID of the merchant.
resources object Contains all objects linked to this payment.
resources.customerId string ID of the customer linked to this payment.
resource.basketId string Basket ID used for this transaction.
resources.typeId string ID of the payment type linked to this payment. This is a types object like card or sepa-direct-debit.
resources.paymentId string ID of the payment.
resources.metadataId string ID of the metadata linked to this payment. Metadata contains merchant information and can be used like a key/value store.
transactions object A list of all transactions related to this payment.
transactions.date date/time Timestamp of this transaction.
transactions.type string Type of this transaction (charge, authorize, cancel-authorize, cancel-charge)
transactions.url string Url to get this resource.
transactions.amount string Amount of this transaction.

Transactions

All transactions related to one payment are listed within the payment resource:

Transactions - payment object

{
    "id": "s-pay-1909",
    "state": {
        "id": 3,
        "name": "partly"
    },
    "amount": {
        "total": "75.0000",
        "charged": "70.0000",
        "canceled": "34.0000",
        "remaining": "5.0000"
    },
    "currency": "EUR",
    "orderId": "",
    "resources": {
        "customerId": "",
        "paymentId": "s-pay-1909",
        "basketId": "",
        "metadataId": "",
        "typeId": "s-crd-ugypfeaazyyg"
    },
    "transactions": [
        {
            "date": "2018-08-17 06:32:54",
            "type": "authorize",
            "url": "https://api.unzer.com/v1/payments/s-pay-1909/authorize/s-aut-1",
            "amount": "100.0000"
        },
        {
            "date": "2018-08-17 06:33:00",
            "type": "cancel-authorize",
            "url": "https://api.unzer.com/v1/payments/s-pay-1909/authorize/s-aut-1/cancels/s-cnl-1",
            "amount": "25.0000"
        },
        {
            "date": "2018-08-17 06:33:15",
            "type": "charge",
            "url": "https://api.unzer.com/v1/payments/s-pay-1909/charges/s-chg-1",
            "amount": "70.0000"
        },
        {
            "date": "2018-08-17 06:33:24",
            "type": "cancel-charge",
            "url": "https://api.unzer.com/v1/payments/s-pay-1909/charges/s-chg-1/cancels/s-cnl-1",
            "amount": "34.0000"
        }
    ]
}

What does this transaction list mean? The following scenario is possible:

  • A customer orders five different products in the online shop of this merchant with his credit card. During the order process, an authorization request of EUR 100 is sent to the Unzer API.

  • The merchant decides to reduce the total amount to EUR 75. For example, parts of this order are not available. The merchant has to send a cancellation request related to the authorization transaction of EUR 25.

  • The first shipment could be sent. It was a partial delivery with a value of EUR 70. In order to enter this amount, the merchant has to create a charge request with the amount of EUR 70.

  • Some of these products may have been damaged during transportation or may not have been as expected. Therefore, the customer returns parts of the delivery. To refund the amount, the merchant can create a cancellation of the fee transaction with an amount of e.g. EUR 34,-.