4.7. A1 Payment data specification

This part describes the JSON payment data to be sent along POST .../charges requests. If a parameter is not mandatory, it can be empty or omitted from the payment data.

Example 4.13. Payment Interface: A1 Field Specification

{
"payment": {
    "type": "object",
    "properties": {
        "paymentAmount": {
            "type": "number",
            "required": "true",
            "description": "The amount charged from the customer, which might include a VAT. If payment data contains product rows, those row amounts do not affect the charged amount
            and they are only for informative purpose. Amount should be the sum of all product's totalRowAmounts.",
            "minimum": 0,65
        },
        "currency": {
            "type": "string",
            "required": "true",
            "description": "Valid values described in ISO 4217. At the moment only allowed currency is "EUR",
            "pattern": "^EUR$"
        },
        "orderNumber": {
            "type": "string",
            "required": "true",
            "description": "Can be used to identify payments in Merchant's Panel.",
            "minLength": 1,
            "maxLength": 64
        },
        "urlSet": {
            "type": "object",
            "properties": {
                "successUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL where the customer is redirected after successful payment. The webshop should generate an identifier into the URL to distiguish a payment to be confirmed.",
                    "minLength": 11,
                    "maxLength": 2048,
                },
                "cancelUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL where the customer is redirected after a failed or cancelled payment.",
                    "minLength": 11,
                    "maxLength": 2048,
                },
                    "notifyUrl": {
                    "type": "string",
                    "required": "true",
                    "description": "URL to be called when the payment has been marked as paid. This URL is called with same GET parameters as successUrl when the payment is marked as paid.
                    Note that notifyUrl request is done by Paytrail server and customer's browser session is not available. NotifyUrl request is normally done within a couple of minutes
                    from completing the payment.",
                    "minLength": 11,
                    "maxLength": 2048,
                }
            }
        },
        "locale": {
            "type": "string",
            "required": "true",
            "description": "Affects the language and how amounts and dates are shown on Paytrail account website if user is redirected there for interaction. Available locales are fi_FI,
            sv_SE and en_US.",
            "minLength": 5,
            "maxLength": 5,
            "pattern": "^[a-z]{2}_[A-Z]{2}$"
        },
        "deliveryAddress": {
            "type": "object",
            "required": "true",
            "description": "",
            "properties": {
                "firstName": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "lastName": {
                    "type": "string",
                    "required": "true",
                    "description": ""
                    "minLength": 1,
                    "maxLength": 64
                },
                "street": {
                    "type": "string",
                    "required": "true",
                    "description": "Address line",
                    "minLength": 1,
                    "maxLength": 64
                },
                "postalCode": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "postalOffice": {
                    "type": "string",
                    "required": "true",
                    "description": "",
                    "minLength": 1,
                    "maxLength": 64
                },
                "country": {
                    "type": "string",
                    "required": "true",
                    "description": "Two characters. Defined in ISO-3166-1"
                    "pattern": "^[A-Z]{2}$"
                }
            }
        },
        "products": {
            "type": "array",
            "required": "true",
            "description": "",
            "maxItems": 500,
            "items": {
                "code": {
                    "type": "string",
                    "required": "false",
                    "description": "Optional product number. This is shown in Merchant's Panel with the product. This might help in associating the product rows to actual products.",
                    "minLength": 1,
                    "maxLength": 16
                },
                "name": {
                    "type": "string",
                    "required": "true",
                    "description": "Free field for product name. Product name will be shown in Merchant's Panel",
                    "minLength": 1,
                    "maxLength": 64
                },
                "quantity": {
                    "type": "number",
                    "required": "true",
                    "description": "Number of products. Usually the value is 1. Can be decimal of format 0.00"
                },
                "unitPrice": {
                    "type": "number",
                    "required": "true",
                    "description": "A price for a single product. Price may be negative to signify a discount. Payment total must be positive ant the format is 0.00. The amounts are for
                    informative purposes only and do not affect the payment total charged from the customer."
                },
                "totalRowAmount": {
                    "type": "number",
                    "required": "true",
                    "description": "This field is used to display row total to the customer. This field must contain the calculated total of quantity * unitPrice to avoid any precision
                    errors when displaying values to customer."
                },
                "vatPercent": {
                    "type": "number",
                    "required": "true",
                    "description": "Vat percent e.g. 25. Supports also decimals like 12.5"
                }
            }
        }
    }
}

Example 4.14. Example A1 Payment JSON

{
    "payment": {
        "paymentAmount": 39.99,
        "currency": "EUR",
        "orderNumber": "ORD12345",
        "urlSet": {
            "successUrl": "https://www.examplewebshop.com/success",
            "cancelUrl": "https://www.examplewebshop.com/cancel",
            "notifyUrl": "https://www.examplewebshop.com/notify"
        },
        "locale": "en_US",
        "deliveryAddress": {
            "firstName": "Penny",
            "lastName": "Paytrail",
            "street": "Lutakonaukio 7",
            "postalCode": "40100",
            "postalOffice": "Jyväskylä",
            "country": "FI"
        },
        "products": [
            {
                "code": "PX923423",
                "name": "Book: How to implement PaytrailConnectAPI",
                "quantity": 1,
                "unitPrice": 39.99,
                "totalRowAmount": 39.99,
                "vatPercent": 24
            }
        ]
    }
}