Order and Customer Details

In order to efficiently process the payment, the merchant needs to provide the order details and customer information. You can provide them either in the JS SDK or REST API.

Field	Type	Description	Example	Mandatory
orderId	`string`	Merchant-defined order ID. Used to identify the specific order in the payment process as well as payment reconciliation reports.	Order-1234/2023	yes
amount	`Amount`	Total order amount. Represents amount of money that is meant to be transferred.	See: `Amount`	yes
orderLines	array of `OrderLine`	Defines items or services that constitutes order.	See: `OrderLine`	yes
customer	`Customer`	Customer information used to process the order.	See: `Customer / Recipient`	yes ^[AFT:no]
recipient	`Customer`	Recipient information used to process the order for AFT Transaction.	See: `Customer / Recipient`	no ^[AFT:yes]
transactionInfo	`string:string`	This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment and will be propagated as a parameter to your callbacks.	marketingAction: christmas2023 source: instagram	no

Account Funding Transactions

For Account Funding Transaction the mandatory parameter requirement is reversed: recipient is mandatory and customer is optional.

Amount

Represent monetary value

Field	Type	Description	Example	Mandatory
value	double	Defines the total amount of the order. Expects number with 2 decimal places.	2049.99	yes
currency	string, matching `^[A-Za-z]{3}$`	Currency code in ISO 4217 format, e.g. USD, EUR, SEK, GBP, etc.	DKK	yes

JS SDKREST API

To setup amout you can use factory method provided:

AltaPayFactory.getAmount(30098.52, 'DKK'),

Amount is part of Session object, that could be updated using a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "orderId": "testOrderId",
        "amount": {
            "value": 30098.52,
            "currency": "DKK"
        },
       ... // other required fields
    }
}'

For complete example please check sections below.

OrderLine

Order lines are representing the items or services that the customer is purchasing as part of the order.

Field	Type	Description	Example	Mandatory
itemId	string	ID of the item in the merchant's system. The ID is visible to the customer in the payment window. Max length is 255 characters.	74121-X-1	yes
description	string	Short description of the item. Max length is 255 characters.	A description of the item	yes
quantity	integer	Quantity of the order line item. Must be a non-negative number.	1	yes
unitPrice	double	Unit price in the currency of the payment represented as decimal value. Unit price is base price of the element purchased, not including taxes or discounts.	100.00	yes
unitCode	string	Unit used to describe the quantity, e.g. kg, pcs, etc. If defined the value has to be 1-8 characters.	kg	no
taxPercent	double	Tax rate of the order line. Non-negative decimal value representing the tax rate in percent.	23.00	no
taxAmount	double	This is the total tax on an order line, before any discounts are applied. It is recommended to use `taxAmount` if possible. If you provide both `taxPercent` and `taxAmount`, the `taxAmount` takes precedence. Must be a non-negative number if provided.	95.10	no
discountPercent	double	The order line's discount in percent. Must be a non-negative number if provided. Will be used to calculate final amount for order line after applying taxes.	15.00	no
goodsType	string	Type of the goods described in order line. Supported values: `shipment` - Covers the cost of shipping `handling` - Covers the cost of handling the order `item` - Covers the cost of a physical product `digital` - Covers the cost of a digital product `discount` - Covers a discount on the order `gift_card` - Covers a gift card `sales_tax` - Covers sales tax on the order	shipment	no
imageUrl	string	URL to the image of the item. It will be displayed on the payment summary pages for providers that supports it (e.g. Klarna). Max length is 255 characters.	https://example.com/image.png	no
productUrl	string	URL to merchant site with the given product. Max length is 255 characters.	https://example.com/image.png	no

Example order value calculations

Tax as percentage

Let's have an order of one order line with given values:

quantity = 5
unitPrice = 100.00
taxPercent = 17.00
discountPercent = 11.00

Then for this order line we got gross amount:

order_line_amount_with_tax = ( quantity * unitPrice ) + ( quantity * unitPrice ) * taxPercent
order_line_amount_with_tax = ( 100 * 5 ) + ( 100 * 5 ) * 17% = 500 + 85 = 585

gross_order_line_amount = order_line_amount_with_tax - order_line_amount_with_tax * discountPercent
gross_order_line_amount = 585 - 585 * 11.00% = 520.65

and total amount of the order will be:

amount = sum of order lines 
amount = 520.65

Tax as amount

Let's have the same order line but with tax represented as amount:

quantity = 5
unitPrice = 100.00
taxAmount = 85.00
discountPercent = 11.00

Then for this order line we got gross amount:

order_line_amount_with_tax = ( quantity * unitPrice ) + taxAmount
order_line_amount_with_tax = 100 * 5 + 85 = 500 + 85 = 585

gross_order_line_amount = order_line_amount_with_tax - order_line_amount_with_tax * discountPercent
gross_order_line_amount = 585 - 585 * 11.00% = 520.65

and total amount of the order will be:

amount = sum of order lines 
amount = 520.65

JS SDKREST API

To setup order lines you can use either a factory method that will create OrderLine object with all required fields:

AltaPayFactory.getOrderLine('123981239', 'MSI GeForce RTX 4090 SUPRIM X 24G', 1, 28010.50)

or you can use OrderLineBuilder in order to any of the optional fields:

AltaPayFactory.getOrderLineBuilder('123981240', 'Delivery', 1, 7.02)  // mandatory fields
    // setting optional fields (you can set only the ones you are interested in)
    .setTaxPercent(23.00)
    .setUnitCode('pcs')
    .setDiscountPercent(11.00)
    .setGoodsType('shipment')
    .setImageUrl('https://example.com/delivery_icon.jpg')
    .setProductUrl('https://example.com/product1')
    .build() // construct OrderLine object

Order lines are part of Session object, that could be updated using a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        ... // other required fields
        "orderLines": [
            {
                "itemId": "123981239",
                "description": "Chaos Emerald",
                "quantity": 1,
                "unitPrice": 28020.5, 
                "unitCode": "pcs",
                "taxPercent": 20.11,
                "discountPercent":15.00,
                "goodsType":"item",
                "imageUrl":"https://example.com/item.png",
                "productUrl":"https://example.com/product/123981239"
            },
            {
                "itemId": "123981240",
                "description": "Delivery",
                "quantity": 1,
                "unitPrice": 2078.02
            }
        ],
       ... // other required fields
    }
}'

For complete example please check sections below.

Address

Addresses are represented in the following way:

Field	Type	Description	Example	Mandatory
street	`string` max length 50	Street name, house and apartment number.	Vesterbrogade 65	yes
city	`string` max length 50	City name.	Copenhagen	yes
region	`string` max length 50	Region field can indicate region or state. Validation might be different depending on the country	Hovedstaden / CA	no ^{[AFT:yes for recipient for countries: CA, US, COL, NIC, yes for customer for countries: US and CA]}
country	`string` matching `^[A-Za-z]{2}$`	Country code represented by ISO 3166 alpha-2-codes.	DK	yes
zipCode	`string` max length 20	Postal code. Validation might be different depending on the country	2860	yes

For examples please see customer section

Organisation

This object is required in case of having a business customer. The details provided here will be used in specific integrations which supports B2B cases.

Organisations are represented in the following way:

Field	Type	Description	Example	Mandatory
name	`string`	The organisation name.	Your Company Ltd	no
entityType	`OrganisationType`	The organisation entity type.	LTD	no
number	`string`	The organisation registration number.	326247-3633	no
vatId	`string`	The organisation VAT number.	RO362473474	no

Customer / Recipient

Customer / Recipient information is required to be provided in order to process the payment. Recipient is currently used only for AFT transactions. Below please find the summary of the fields.

Field	Type	Description	Example	Mandatory
firstName	`string`		John	no
lastName	`string`		Doe	no
email	`string`		john.doe@email.com	no
phoneNumber	`string` matching `^\\+?[0-9]{2,3}[0-9]{6,12}$`		+4576543210	no
billingAddress	`Address`		See: `Address`	no ^[AFT:yes]
shippingAddress	`Address`		See: `Address`	no
username	`string`		testUser	no ^{[AFT:yes for customer for ZA]}
birthdate	`string` in format `yyyy-MM-dd`		1990-02-22	no ^{[AFT:yes for customer, yes for recipient for UK]}
accountIdentifier	`string` / `numeric`	Identifier of an account (PAN or account number) - Typically, it is the reference to the voucher/wallet. Not the original card number.	myAccount / 1234 6789	no ^{[AFT:yes for recipient]}

Account Funding Transactions

Please note that mandatory requirement can be different per acquirer so this is just a guideline.

JS SDKREST API

In order to create Customer or Recipient object you can use factory method provided with some basic fields included:

AltaPayFactory.getCustomer(
    'John',
    'Doe',
    'example@email.com',
    '+4560020030',
    AltaPayFactory.getAddress('Vesterbrogade 65', 'Copenhagen', 'DK', '2860'),
    AltaPayFactory.getAddress('Gyngemose Parkvej 50', 'Søborg', 'DK', '2860')
)

or use CustomerBuilder to configure all the optional values:

AltaPayFactory.getCustomerBuilder()
    .setFirstName('John')
    .setLastName('Doe')
    .setEmail('test@example.com')
    .setPhoneNumber('+4512345678')
    .setUsername('testUserName')
    .setBirthdate('1995-03-21')
    .setAccountIdentifier('myAccount')
    .setBillingAddress(AltaPayFactory.getAddress('Gyngemose Parkvej 50', 'Soeborg', 'DK', '2860'))
    .setShippingAddress(AltaPayFactory.getAddress('Gyngemose Parkvej 50', 'Soeborg', 'DK', '2860'))
    .setOrganisation(AltaPayFactory.getOrganisation('Company', OrganisationType.LTD, '21636', 'RO2343'))
    .build()

Customer is part of Session object, that could be updated using a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        ... // other required fields
        "customer": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "test@example.com",
            "username": "testUserName",
            "birthdate": "1990-02-22",
            "billingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            },
            "shippingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            },
            "organisation": {
                "name": "Zeta Electronics Gold GmbH",
                "vatId": "DE812345678",
                "entityType": "LTD",
                "number": "HRB934855"
            }
        }
        ... // and / or
        "recipient": {
            "firstName": "Sherlock",
            "lastName": "Holmes",
            "email": "test-recipient@example.com",
            "phoneNumber": "+4584758831",
            "username":"sholmes",
            "accountIdentifier":"myAccount",
            "birthdate": "1999-10-15",
            "billingAddress": {
                "street": "Baker Street 221B",
                "city": "London",
                "country": "GB",
                "zipCode": "NW1",
                "region": "LON"
            }
        }
    }
}'

For complete example please check sections below.

Examples

Minimal request

JS SDKREST API

After paymentSession is created, it should be configured with order with at minimum orderId, amount and order lines

paymentSession.setOrder(
    AltaPayFactory.getOrderBuilder(
        'testOrderId',
        AltaPayFactory.getAmount(22094.00, 'DKK')
    )
    .setOrderLines([
            AltaPayFactory.getOrderLineBuilder('123981239', 'Chaos Emerald', 1, 20000.00) 
                .setTaxPercent(23.00)
                .setUnitCode('pcs')
                .setDiscountPercent(11.00)
                .setGoodsType('item')
                .setImageUrl('https://example.com/emerald.jpg')
                .setProductUrl('https://example.com/product1')
                .build()
    ])
    .build()
);

After session is created, it should be configured with order that contains at minimum orderId, amount and order lines. To do that, you need to make a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header providing all the details in the body.

Example below contains very basic request.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "orderId": "testOrderId",
        "amount": {
            "value": 22094.00,
            "currency": "DKK"
        },
        "orderLines": [
            {
                "itemId": "123981239",
                "description": "Chaos Emerald",
                "quantity": 1,
                "unitPrice": 20000, 
                "unitCode": "pcs",
                "taxPercent": 23.00,
                "discountPercent":11.00,
                "goodsType":"item",
                "imageUrl":"https://example.com/item.png",
                "productUrl":"https://example.com/product/123981239"
            },
            {
                "itemId": "123981240",
                "description": "Delivery",
                "quantity": 1,
                "unitPrice": 200
            }
        ]
    }
}'

Standard order with customer data

JS SDKREST API

After paymentSession is created, in more standard scenario it should be configured with order and customer details

paymentSession.setOrder(
    AltaPayFactory.getOrderBuilder(
        'testOrderId',
        AltaPayFactory.getAmount(22094.00, 'DKK')
    )
    .setOrderLines([
            AltaPayFactory.getOrderLineBuilder('123981239', 'Chaos Emerald', 1, 20000.00) 
                .setTaxPercent(23.00)
                .setUnitCode('pcs')
                .setDiscountPercent(11.00)
                .setGoodsType('item')
                .setImageUrl('https://example.com/emerald.jpg')
                .setProductUrl('https://example.com/product1')
                .build(),
            AltaPayFactory.getOrderLine('123981240', 'Delivery', 1, 200)
    ])
    .setCustomer(AltaPayFactory.getCustomerBuilder()
        .setFirstName('John')
        .setLastName('Doe')
        .setEmail('example@example.com')
        .setPhoneNumber('+4560020030')
        .setBillingAddress(AltaPayFactory.getAddressBuilder('Vesterbrogade 65', 'Copenhagen', 'DK', '2860').setFirstName('John').setLastName('Doe').setRegion('REG').build())
        .setShippingAddress(AltaPayFactory.getAddress('Gyngemose Parkvej 50', 'Søborg', 'DK', '2860'))
        .build()
    )
    .build()
);

In more standard scenario, it should be configured with order and customer details. To do that, you need to make a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header providing all the details in the body.

Example below contains all the necessary data including callbacks which are described in the next section.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "orderId": "testOrderId",
        "amount": {
            "value": 22094.00,
            "currency": "DKK"
        },
        "orderLines": [
            {
                "itemId": "123981239",
                "description": "Chaos Emerald",
                "quantity": 1,
                "unitPrice": 20000, 
                "unitCode": "pcs",
                "taxPercent": 23.00,
                "discountPercent":11.00,
                "goodsType":"item",
                "imageUrl":"https://example.com/item.png",
                "productUrl":"https://example.com/product/123981239"
            },
            {
                "itemId": "123981240",
                "description": "Delivery",
                "quantity": 1,
                "unitPrice": 200
            }
        ],
        "customer": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "test@example.com",
            "billingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            },
            "shippingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            }
        }
    }
}'

AFT orders

Order with `customer` and `recipient` information

JS SDKREST API

For AFT transactions recipient is mandatory. In case customer information (known also as sender information) is different than recipient you should provide both elements.

paymentSession.setOrder(
    AltaPayFactory.getOrderBuilder(
        'testOrderId',
        AltaPayFactory.getAmount(22094.00, 'DKK')
    )
    .setOrderLines([
            AltaPayFactory.getOrderLineBuilder('123981239', 'Chaos Emerald', 1, 20000.00) 
                .setTaxPercent(23.00)
                .setUnitCode('pcs')
                .setDiscountPercent(11.00)
                .setGoodsType('item')
                .setImageUrl('https://example.com/emerald.jpg')
                .setProductUrl('https://example.com/product1')
                .build(),
            AltaPayFactory.getOrderLine('123981240', 'Delivery', 1, 200)
    ])
    .setCustomer(AltaPayFactory.getCustomerBuilder()
        .setFirstName('John')
        .setLastName('Doe')
        .setEmail('example@example.com')
        .setPhoneNumber('+4560020030')
        .setBillingAddress(AltaPayFactory.getAddressBuilder('Vesterbrogade 65', 'Copenhagen', 'DK', '2860').setFirstName('John').setLastName('Doe').setRegion('REG').build())
        .setShippingAddress(AltaPayFactory.getAddress('Gyngemose Parkvej 50', 'Søborg', 'DK', '2860'))
        .build()
    )
    .setRecipient(AltaPayFactory.getCustomerBuilder()
        .setFirstName('Sherlock')
        .setLastName('Holmes')
        .setEmail('test-recipient@example.com')
        .setPhoneNumber('+5555551234')
        .setUsername('sholmes')
        .setAccountIdentifier('myAccount')
        .setBirthdate('1854-01-06')
        .setBillingAddress(AltaPayFactory.getAddressBuilder('Baker Street 221B', 'London', 'GB', 'NW1').setRegion('LON').build())
        .build()
    )
    .build()
);

After session is created, it should be configured with order. To do that, you need to make a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header providing all the details in the body.

For AFT transactions recipient is mandatory. In case customer information (known also as sender information) is different than recipient you should provide both elements.

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "orderId": "testOrderId",
        "amount": {
            "value": 22094.00,
            "currency": "DKK"
        },
        "orderLines": [
            {
                "itemId": "123981239",
                "description": "Chaos Emerald",
                "quantity": 1,
                "unitPrice": 20000, 
                "unitCode": "pcs",
                "taxPercent": 23.00,
                "discountPercent":11.00,
                "goodsType":"item",
                "imageUrl":"https://example.com/item.png",
                "productUrl":"https://example.com/product/123981239"
            },
            {
                "itemId": "123981240",
                "description": "Delivery",
                "quantity": 1,
                "unitPrice": 200
            }
        ],
        "customer": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "test@example.com",
            "billingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            },
            "shippingAddress": {
                "street": "Gyngemose Parkvej 50",
                "city": "Soeborg",
                "country": "DK",
                "zipCode": "2860"
            }
        },
        "recipient": {
            "firstName": "Sherlock",
            "lastName": "Holmes",
            "email": "test-recipient@example.com",
            "phoneNumber": "+4584758831",
            "username":"sholmes",
            "accountIdentifier":"myAccount",
            "birthdate": "1999-10-15",
            "billingAddress": {
                "street": "Baker Street 221B",
                "city": "London",
                "country": "GB",
                "zipCode": "NW1",
                "region": "LON"
            }
        }
    }
}'

Order with `recipient` information only

JS SDKREST API

For AFT transactions recipient is mandatory. In case customer information (known also as sender information) is the same as recipient you may skip the customer

paymentSession.setOrder(
    AltaPayFactory.getOrderBuilder(
        'testOrderId',
        AltaPayFactory.getAmount(22094.00, 'DKK')
    )
    .setOrderLines([
            AltaPayFactory.getOrderLineBuilder('123981239', 'Chaos Emerald', 1, 20000.00) 
                .setTaxPercent(23.00)
                .setUnitCode('pcs')
                .setDiscountPercent(11.00)
                .setGoodsType('item')
                .setImageUrl('https://example.com/emerald.jpg')
                .setProductUrl('https://example.com/product1')
                .build(),
            AltaPayFactory.getOrderLine('123981240', 'Delivery', 1, 200)
    ])
    .setRecipient(AltaPayFactory.getCustomerBuilder()
        .setFirstName('Sherlock')
        .setLastName('Holmes')
        .setEmail('test-recipient@example.com')
        .setPhoneNumber('+5555551234')
        .setUsername('sholmes')
        .setAccountIdentifier('myAccount')
        .setBirthdate('1854-01-06')
        .setBillingAddress(AltaPayFactory.getAddressBuilder('Baker Street 221B', 'London', 'GB', 'NW1').setRegion('LON').build())
        .build()
    )
    .build()
);

After session is created, it should be configured with order. To do that, you need to make a PUT request on /checkout/v1/api/session/{sessionId} endpoint with JWT token in the header providing all the details in the body.

For AFT transactions recipient is mandatory. In case customer information (known also as sender information) is the same as recipient you may skip the customer

curl --location --request PUT 'https://{checkout-api-url}.altapaysecure.com/checkout/v1/api/session/{sessionId}' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "order": {
        "orderId": "testOrderId",
        "amount": {
            "value": 22094.00,
            "currency": "DKK"
        },
        "orderLines": [
            {
                "itemId": "123981239",
                "description": "Chaos Emerald",
                "quantity": 1,
                "unitPrice": 20000, 
                "unitCode": "pcs",
                "taxPercent": 23.00,
                "discountPercent":11.00,
                "goodsType":"item",
                "imageUrl":"https://example.com/item.png",
                "productUrl":"https://example.com/product/123981239"
            },
            {
                "itemId": "123981240",
                "description": "Delivery",
                "quantity": 1,
                "unitPrice": 200
            }
        ],
        "recipient": {
            "firstName": "Sherlock",
            "lastName": "Holmes",
            "email": "test-recipient@example.com",
            "phoneNumber": "+4584758831",
            "username":"sholmes",
            "accountIdentifier":"myAccount",
            "birthdate": "1999-10-15",
            "billingAddress": {
                "street": "Baker Street 221B",
                "city": "London",
                "country": "GB",
                "zipCode": "NW1",
                "region": "LON"
            }
        }
    }
}'

Order and Customer Details

Amount

OrderLine

Example order value calculations

Tax as percentage

Tax as amount

Address

Organisation

Customer / Recipient

Examples

Minimal request

Standard order with customer data

AFT orders

Order with customer and recipient information

Order with recipient information only

Order with `customer` and `recipient` information

Order with `recipient` information only