5.8. Merchant API v1

5.8.1. Service description

Paytrail Merchant API is a REST service for merchants where they can create and cancel refunds, opt to receive updates for any status changes of a refund and fetch settlement, payment and refund details. If you encounter any problems during the API integration, don't hesitate to contact our technical support at .

Service address: https://api.paytrail.com/merchant/v1/

5.8.2. Authentication

API requests are authenticated through HTTP authentication. See Authorization header description for details.

5.8.3. Accessing the API

5.8.3.1. Headers

Table 5.14. Required headers

HeaderDescription
TimestampRequest timestamp. Must be the same as what is used for signature calculation.
Content-MD5Base64 encoded MD5 sum for the request body contents.
Authorization Authentication details. Format: PaytrailMerchantAPI <merchant id>:<signature>. The signature is a BASE64 encoding of binary SHA256 HMAC of request details using merchant secret as the private key. Calculation formula:
base64_encode(
    hmac_sha256_binary(
        :requestMethod + "\n" +
            :url + "\n" +
            "PaytrailMerchantAPI " + :merchantId + "\n" +
            :timestamp + "\n" +
            :base64ContentMd5,
        :merchantSecret
    )
)
                                

Example 5.17. Example of signature calculation for refund creation

Table 5.15. Signature parameters

Field nameValue
API key (Merchant ID)13466
Merchant secret6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ
Timestamp2015-05-01T12:00:00+0200
Order number15153
URL/merchant/v1/payments/15153/refunds
MethodPOST
Content
{
   "email": "john.doe@mycustomer.com",
   "notifyUrl": "https://example.com/notify",
   "rows": [
      {
         "amount": 1599,
         "description": "Long sleeve shirt",
         "vatPercent": 2400
      }
   ]
}
                                    
Note that there are no newlines before or after first and last curly braces. Newline character here is \n.

Calculated signature: W4P34H0xiTB202rsjtZIsMlEPQLRoS60d26KKl0zwZo=


5.8.3.2. Responses

The API has general responses that may be returned for all of the API queries.

Table 5.16. General HTTP responses

CodeDescription
HTTP 202Accepted + Location header indicating created resource + No content in body
HTTP 204No content + No specific headers + No content in body
HTTP 400Bad request (invalid JSON)
HTTP 403Forbidden (invalid API name or invalid signature)
HTTP 404Not found
HTTP 405Method not allowed
HTTP 503Service temporarily unavailable

The response body is a JSON message when a status code 4xx or 5xx is returned.

Table 5.17. General error codes and workarounds

Error code string and HTTP codeDescriptionWorkaround
invalid-signature (HTTP 403)Signature is not validCheck signature calculation
invalid-api-name (HTTP 403)API name is not validCheck that API name is PaytrailMerchantAPI
merchant-inactive (HTTP 403)Merchant specified in API key is inactivePlease contact customer support
refunds-not-enabled (HTTP 403)Merchant does not have Refunds enabledPlease contact customer support
invalid-json (HTTP 400)JSON parsing failedCheck that JSON input is valid
service-unavailable (HTTP 503)Refunding service is currently unavailablePlease try again later

Example 5.18. JSON message structure with invalid API name

{
  "error": {
    "title": "invalid-api-name",
    "description": "API name is not valid",
    "workaround": "Check that API name is PaytrailMerchantAPI"
  }
}
                        

5.8.4. Create Refund

5.8.4.1. Request

POST /merchant/v1/payments/:orderNumber/refunds

Refunds are created using order numbers as identifiers. Merchants must use unique order numbers for Paytrail Merchant API to be able to link each refund to a single payment. The customer will be sent an email upon successful refund creation.

Table 5.18. Parameters

NameTypeRequired/OptionalDescription
emailstringr/o When specified, the given email will be used for the refund. Required if the payment was made through the S1 interface if payment is not paid using card (email is not required for card payments).
rowsarray [1:500]r
amount
(integer, required) How much money to refund in cents (>0 – 2 000 000) with VAT included. The payment must have this much money left to refund, and for the right VAT percent, in case E1 or E2 interface with product rows was used.
vatPercent
(integer, required/not allowed) Which VAT percent to allocate the refund to, expressed in fractions of a hundred (0 – 10 000).
description
(string [2000], optional) Description for the refund shown as product row name. This is visible to the customer as well.
notifyUrlstringoValid webhook URL to call when a refund's status updates

Table 5.19. Return codes and workarounds

Code string and HTTP codeDescriptionWorkaround
HTTP 202Successful refund request, refund was created 
invalid-refund-rows (HTTP 400)The amount of rows to refund is invalidCheck that you have at least one and less than the maximum amount of refund rows in your request
invalid-amount (HTTP 400)A row sum is invalidCheck that all refund rows have sums and that the sums conform to requirements
invalid-vat-percent (HTTP 400)A VAT percent is invalidCheck that all refund rows have VAT percents for E1 or E2 payments and that they conform to requirements
invalid-description (HTTP 400)Description is too longCheck that none of your descriptions is longer than the maximum length
invalid-notify-url (HTTP 400)Notify URL is not a valid URLCheck your notify URLs
invalid-key (HTTP 400)An unknown key was encounteredCheck that your refund rows don't contain any extra keys
missing-email (HTTP 400) There was no email given for S1 payment refund request (email is mandatory for bank and Collector refunds) Add customer's email address to the refund request
invalid-interface (HTTP 400)Payments with older simple interface version 1 or 3 can't be refundedUse our newer payment interface so that you can create refunds in the future
nonunique-payment-identifier (HTTP 400)Multiple payments could be found for the same order numberMake sure your order numbers are unique
payment-not-found (HTTP 404)No payment was found with given order numberCheck that your order number matches a payment made through our system
payment-interface-type-does-not-support-refunding (HTTP 405)Refund request was made against a payment of unsupported interface typeCheck that the refund request was made against a payment made via Paytrail and not via a third party payment service
payment-method-does-not-support-refunding (HTTP 405)Refund request was made against a payment of unsupported payment methodCheck that the refund request was made for a payment made with method which supports refunding
payment-status-does-not-support-refunding (HTTP 405)Payment was in invalid state for refund to be madeCheck that the payment is in successfully completed state

5.8.5. Notify URL call

Paytrail calls the notify URL with a GET request when the refund status changes. The received notification must be acknowledged by responding with an HTTP status in the 200-299 range. Status updates will be sent in the order they occur. If an update is not acknowledged by the receiving end, subsequent updates to that refund are postponed until next retry round. Updates will be retried after 1, 3, 6, 10, 15, 21, 28, 36, 45 and 55 hours, after which the notification is discarded. This may cause some updates to be skipped if the notification URL endpoint cannot be contacted within 55 hours.

Table 5.20. Parameters sent with each notify call

NameDescription
refundTokenRefund's token
oldStatusRefund's previous status
newStatusRefund's new status
signatureSignature to ensure the update comes from Paytrail. Calculation: sha256(:refundToken + '|' + :oldStatus + '|' + :newStatus + '|' + :merchantSecret)

Table 5.21. Refund statuses

Status stringDescription
createdRefund created. Never used as newStatus, since notify is not sent when refund is created
consumer-data-collectedCustomer's IBAN has been received
waiting-credit-card-refund-processRefund is created and waiting for credit card processor to accept or reject the refund request
settlement-startedRefund has been added to outgoing settlements
completed Refund has been paid to the customer and in case of bank or collector refund reduced from merchant's settlements
cancelled-by-merchantRefund was cancelled by the merchant
cancelled-by-timeoutRefund was not accepted by the customer within the time limit of 30 days, or there have not been enough payments within 60 days to cover the refund sum
cancelled-by-terminationRefund was cancelled when the merchant's contract with Paytrail was terminated
failedCredit card refund process has failed and refund is cancelled

Figure 5.5. Status flow diagram for bank payments

Status flow diagram for bank payments

Figure 5.6. Status flow diagram for invoices (Collector)

Status flow diagram for invoices (Collector)

Figure 5.7. Status flow diagram for cards

Status flow diagram for cards

5.8.6. Refund cancellation

DELETE /merchant/v1/refunds/:refundToken

The customer will be notified of a successful refund cancellation by email. DELETE is not allowed for card refunds. Response in case of card refund is 405.

Table 5.22. Return codes and workarounds

Code string and HTTP codeDescriptionWorkaround
HTTP 204Refund was cancelled successfully 
refund-not-found (HTTP 404)Refund was not found with given tokenCheck that you gave a non-empty token that points to an existing refund
invalid-refund-status (HTTP 405)Refund cannot be cancelled from its current stateCheck refund's status from Merchant's Panel. Note that DELETE is not allowed for card refunds. Response in case of card refund is 405.

5.8.7. Settlements

GET /merchant/v1/settlements?fromDate=from&toDate=to

Returns settlements created between selected timespan.

Table 5.23. Parameters

NameTypeMandatory/OptionalFormatDescription
fromdatemandatoryyyyy-mm-ddInvalid date format or invalid time span will return empty response (404 and invalid-date-format error)
todatemandatoryyyyy-mm-ddInvalid date format or invalid time span will return empty response (404 and invalid-date-format error)

Table 5.24. Structure and detailed information on returned values

Parameter nameDatatypeFormatOccurenceMax length/valueValue contains
 array 1 This is the main level array that contains all found settlement objects
 hash 0-N A settlement object
idstring 164 
referenceNumbernumber 132 
settledAmountnumber 150000000How much money was settled to merchant? Amount is in the currency's smallest unit. e.g. in Euro cents
settledAtdatetimestamp1null / dateWhen the settlement was paid to merchant's bank account. Can be null if it's not yet paid.
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"

Example 5.19. Example request


GET /merchant/v1/settlements?fromDate=2015-01-01&amp;toDate=2015-02-01 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>: <base64 encoded 44 characters>

                

Example 5.20. Example response


HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "id": "1234567",
        "referenceNumber": "123456123456",
        "settledAt": "2015-03-05",
        "settledAmount": 7865,
        "currency": "EUR"
    }
]

                

Table 5.25. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-date-range404Invalid date rangeCheck that date range is not over two months
invalid-date-format404Invalid date formatCheck that date format is correct (yyyy-mm-dd)

5.8.8. Settlement details

GET /merchant/v1/settlements/:id

Returns settlement details.

Table 5.26. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatorySettlement whose details are requested

Table 5.27. Structure and detailed information on returned values

Parameter nameDatatypeFormatOccurenceMax length/valueValue contains
 hash 1 A settlement object
idstring 164 
referenceNumbernumber 132 
settledAmountnumber 150000000How much money was settled to merchant? Amount is in the currency's smallest unit. e.g. in Euro cents
settledAtdatetimestamp1null / dateWhen the settlement was paid to merchant's bank account. Can be null if it's not yet paid.
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
 array   This is the main level array that contains all found payment objects
payments  1-N a payment object
idnumber 112 
referenceNumbernumber 132 
orderNumberstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "waiting payment", "paid", "cancelled", "waiting acceptance"
paymentMethodIdnumber 1 Payment method id, see available methods from selection and visibility of payment methods
payerNamestring 132Payer name, only available for bank payments
amounts  1 Payment amounts object
originalnumber 150000000Amount provided in payment data from web shop
chargednumber 150000000Charged amount
settlednumber 150000000Amount settled to merchant
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
consumerFees  1 Payment consumer fees object
paymentMethodnumber 150000000Payment method fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
merchantFees  1 Payment merchant fees object
transactionnumber 150000000Transaction fee
provisionnumber 150000000Provision
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
paymentServiceProviderstring 1  Possible values: "Paytrail"
paymentServiceTypestring 1  Possible values: "collecting", "direct"
refunds  0-N A refund object (refunds linked to payment)
 array   This is the main level array that contains all found refund objects
idstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "created", "account linked", "settlement linked", "balancing created", "settlement created", "completed", "cancelled by merchant", "cancelled by timeout", "cancelled by termination"
paymentIdnumber 112 
updatedAtdatetimestamp1null / date 
originalAmountnumber 150000000Original fee
settledAmountnumber 150000000Amount settled to merchant
merchantFees  1 Payment merchant fees object
transactionFeenumber 150000000Transaction fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
settlementIdstring 164 
refundsstring 0-N A refund object (refunds linked to settlement)
 array   This is the main level array that contains all found refund objects
idstring 164 
createdAtdatetimestamp1date 
statusstring 1  Possible values: "created", "account linked", "settlement linked", "balancing created", "settlement created", "completed", "cancelled by merchant", "cancelled by timeout", "cancelled by termination"
paymentIdnumber 112 
updatedAtdatetimestamp1null / date 
originalAmountnumber 150000000Original fee
settledAmountnumber 150000000Amount settled to merchant
merchantFees  1 Payment merchant fees object
transactionFeenumber 150000000Transaction fee
currencystring 13ISO 3 letter symbol for settlement currency e.g. "EUR"
settlementIdstring 164 

Example 5.21. Example request


GET /merchant/v1/settlements/123451234512345 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>: <base64 encoded 44 characters>

            

Example 5.22. Example response


HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "1234567",
    "referenceNumber": "123456123456",
    "settledAt": "2015-03-05"
    "settledAmount": 7865,
    "currency": "EUR",
    "payments": [
        {
            "id": "176456276154",
            "referenceNumber": "10034",
            "orderNumber": "ORDER-2",
            "createdAt": "2015-01-02T12:00:03+00:00",
            "status": "paid",
            "paymentMethodId": 2,
            "payerName": "Teppo Teik\u00e4l\u00e4inen",
            "amounts": {
                "original": 10000,
                "charged": 10000,
                "settled": 9965,
                "currency": "EUR"
            },
            "consumerFees": {
                "paymentMethod": 0,
                "currency": "EUR"
            },
            "merchantFees": {
                "transaction": -35,
                "provision": 0,
                "currency": "EUR"
            },
            "paymentServiceProvider": "Paytrail",
            "paymentServiceType": "collecting",
            "settlementId": "1234567",
            "refunds": [
                {
                    "id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
                    "createdAt": "2015-01-02T14:00:02+00:00",
                    "status": "created",
                    "paymentId": "176456276154",
                    "updatedAt": "2015-01-02T14:00:03+00:00",
                    "originalAmount": -2000,
                    "settledAmount": -2100,
                    "merchantFees": {
                        "transactionFee": -100
                    },
                    "currency": "EUR",
                    "settlementId": "1234567"
                }
            ]
        }
    ],
    "refunds": [
        {
            "id": "GbLhiDev1rNh3SnfjJVvevRExTPq15stFrVsqWKm",
            "createdAt": "2015-01-01T14:14:09+00:00",
            "status": "paid",
            "paymentId": "92736276154",
            "updatedAt": "2015-01-01T14:18:08+00:00",
            "originalAmount": -3000,
            "settledAmount": -3100,
            "merchantFees": {
                "transactionFee": -100
            },
            "currency": "EUR",
            "settlementId": "1234567"
        }
    ],
}

            

Table 5.28. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-settlement-id404Invalid idCheck settlement id format

5.8.9. Payment details

GET /merchant/v1/payments/:id

Returns payment details.

Table 5.29. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatoryPayment whose details are requested (customer's payment identification code without hyphen)

Example 5.23. Example request

        
GET /merchant/v1/payments/176456276153 HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>:<base64 encoded 44 characters>

            

Example 5.24. Example response

        
HTTP/1.1 200 OK
Content-Type: application/json
{
	"id": "176456276154",
	"referenceNumber": "10034",
	"orderNumber": "ORDER-2",
	"createdAt": "2015-01-02T12:00:03+00:00",
	"status": "paid",
	"paymentMethodId": 2,
	"payerName": "Teppo Teikäläinen",
	"amounts": {
		"original": 10000,
 		"charged": 10000,
		"settled": 9965,
 		"currency": "EUR"
 	},
 	"consumerFees": {
		"paymentMethod": 0,
		"currency": "EUR"
 	},
 	"merchantFees": {
		"transaction": -35,
		"provision": 0,
		"currency": "EUR"
 	},
	"paymentServiceProvider": "Paytrail",
	"paymentServiceType": "collecting",
	"settlementId": "1234567",
	"refunds": [
	 	{
			"id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
 			"createdAt": "2015-01-02T14:00:02+00:00",
			"status": "created",
			"paymentId": "176456276154",
			"updatedAt": "2015-01-02T14:00:03+00:00",
			"originalAmount": -2000,
			"settledAmount": -2100,
			"merchantFees": {
			 	"transactionFee": -100
			},
			"currency": "EUR",
 			"settlementId": "1234567"
	 	}
	]
}

            

Table 5.30. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-consumer-payment-id404Invalid consumer payment idCheck consumer payment id - you can check the value from Merchant's Panel

5.8.10. Refund details

GET /merchant/v1/refunds/:id

Returns refund details.

Table 5.31. Parameters

NameTypeMandatory/OptionalDescription
idstringmandatoryRefund token whose details are requested

Example 5.25. Example request

                
GET /merchant/v1/refunds/DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh HTTP/1.1
Timestamp: 2012-12-31T12:00:00+0200
Content-MD5: <base64 encoded 24 characters>
Authorization: PaytrailMerchantAPI <merchant id>:<base64 encoded 44 characters>

            

Example 5.26. Example response

                
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "DA2OTA4NWVmYTRiMDUyMWI4OGNkNjkxNzBh",
    "createdAt": "2015-01-02T14:00:02+00:00",
    "status": "created",
    "paymentId": "176456276154",
    "updatedAt": "2015-01-02T14:00:03+00:00",
    "originalAmount": -2000,
    "settledAmount": -2100,
    "merchantFees": {
        "transactionFee": -100
    },
    "currency": "EUR",
    "settlementId": "1234567"
}

            

Table 5.32. Resource specific error messages

Error code stringHTTP statusDescriptionWorkaround
invalid-refund-token404Invalid refund tokenCheck refund token - you can check the value from Merchant's Panel