createPaymentRequest
The createPaymentRequest method initiates a new payment by sending a payment request with all relevant payment information to the gateway. It is the preferred way of enabling a customer to pay via the AltaPay payment platform. It supports all the Alternative Payment Methods that are supported on our platform, and even though it redirects the customer to AltaPay, you (the merchant) keep complete control of the payment page. You can easily and dynamically adapt it so that, as far as your customer is concerned, they never leave your shop.
On receipt of the payment request, you get the payment page URL.
- The Url element contains the URL you should direct your customers to.
- The DynamicJavascriptUrl element contains a URL you can use to dynamically load the payment page in an iFrame. For more information, see Loading the payment page dynamically.

Test URL | https://testgateway.altapaysecure.com/merchant/API/<method> |
Production URL | https://<YourShopName>.altapaysecure.com/merchant/API/<method> |
For information about the payment flow process, see Payment flow process (Merchant API).
The URLs show a payment page that for credit card payments, without custom styling, looks like this:
For instructions on how to create custom styling for the payment page, see Styling the payment page (callback_form).
For information about the XML Schema Definition for API responses, see API Response structure (XML).
If surcharging is disabled on your terminal, but rules have been set up, the calculateSurcharge method calculates the surcharge based on those rules. As of January 2018, surcharging consumer credit cards in the EU, Norway, and Iceland is prohibited.
Request parameters
The API call does not happen in the browser, which means that users cannot tamper, or even see, the data posted to the gateway. You do not have to pass a check sum for the customer information.
The following parameters are mandatory for all integrations:
Parameter |
Description |
Type |
Mandatory |
---|---|---|---|
terminal |
The terminal determines the payment method and currency. For more information, see AltaPay's Payment Gateway. This is the title of your terminal, found under Home > Terminal Settings in the Merchant Interface. You can use variables in the terminal parameter. For example, if you want to call My EUR Terminal, you can set the terminal parameter value to 'My {currency} Terminal', where {currency} references the value of the currency parameter. |
string |
Yes |
shop_orderid |
This is the internal ID of the order in your webshop. In most integrations, you can use the same order ID for up to four orders. |
[a-zA-Z0-9]{1,100} PayPal and MobilePay only accept order IDs of 50 characters or less |
Yes |
amount |
This is the payment amount. |
float |
Yes |
currency |
This is the payment currency. It must be specified in an ISO-4217 format, either using the 3-digit numeric code, or the 3-letter character code. For more information about ISO-4217 currency codes, see https://en.wikipedia.org/wiki/ISO_4217. |
[0-9]{3} or [A-Z]{3} |
Yes |
Select from the drop-down list to see the parameters relevant for that method/acquirer:

Parameter |
Description |
Type |
Mandatory |
---|---|---|---|
language |
The language in which the payment form is displayed. For more information about supported language codes, see Supported languages. If the language parameter is not set, the language is derived from the browser's Accept-Language HTTP header field. If none of the browser languages are supported, the default is English, en. If the language you set is not supported, an error is returned. |
[a-z]{2} |
|
transaction_info |
This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment in the call to createPaymentRequest. |
Array Maximum 50 entries of maximum 255 characters each. |
|
type |
This is the authorization type. For more information, see Payment request types:
It is not possible to create a payment request with type=payment. If the type is set to payment, it is automatically changed to paymentAndCapture. |
string |
|
ccToken |
This is the credit card token value. By using a credit card token from a previous payment, your customer won't have to enter credit card details again. To enable this, select the Enable credit card token check box under Home > Terminal Settings in the Merchant Interface. |
[0-9a-f]{41} |
|
sale_reconciliation_identifier |
This is the sales reconciliation identifier, used in the reconciliation CSV files you can download from the Merchant Information Interface, or by using the getCustomReport method. For more information, see getCustomReport.This parameter can only be used when the type parameter is set to paymentAndCapture. |
String{0,100} |
|
sale_invoice_number |
This is the invoice number for the capture. |
String{0,100} |
|
fraud_service |
Setting the fraud_service parameter lets you select a different fraud detection service on the payment level. |
none maxmind red test |
|
cookie |
This is the cookie that will be sent back to all your callback URLs. For example, if your cookie parameters are set to |
String |
|
payment_source |
This identifies the source of the payment. The default value is eCommerce. moto is treated as telephone_order. |
eCommerce mobi moto mail_order telephone_order |
|
shipping_method |
Fraud detection services can use this parameter in the fraud detection calculations. |
LowCost DesignatedByCustomer International Military NextDay Other StorePickup TwoDayService ThreeDayService |
|
customer_created_date |
This is the date when the customer account was first created in your shopping system. Fraud detection services use this parameter in the fraud detection calculations. |
Date (yyyy-mm-dd) |
|
organisation_number |
this is the company registration number (CRN), and is used to identify the company and verify the fact that it is a entity registered with the relevant authority, for example, Companies House in the UK. Do not confuse this with the customer_info[vat_id], although in some countries the number may be the same. To ensure that the organisation number field is pre-populated on the invoice payment form, set the organisation_number parameter. |
String{0,20} |
Yes, if the customer_info[type]=business |
account_offer |
If you set account_offer to required, the customer must have an account set up to be able to use invoice payment. To disable the account for a specific customer, set account_offer to disabled. |
required disabled |
|
sales_tax |
The sales tax amount. Indicates how much of the gross amount that was sales tax, e.g. VAT (UK) or Moms (DK). |
float |
Yes
|

Parameter | Description | Type | Mandatory |
---|---|---|---|
customer_info[username] | The customer's e-user name or user id. This uniquely identifies the user in your system. | string | |
customer_info[type] | Indicator of whether the customer is an individual or a business | privatebusiness | Private is assumed if not specified |
customer_info[company_name] | Name of the customer, if the customer type is Business | string | Yes, if the customer_info[type]=business |
customer_info[company_type] | The nature of the company |
ltd - limited company plc - public limited company public_institution - public institution Other - all other company types |
Yes, if the customer_info[type]=business |
customer_info[vat_id] | The company's VAT registration number | string | Yes, if the customer_info[type]=business |
customer_info[shipping_att] | The name of the person receiving the purchase on behalf of the company | string | Used if the customer_info[type]=business; optional but recommended |
customer_info[shipping_lastname] |
The last name for the customer's shipping address. |
String | |
customer_info[shipping_firstname] |
The first name for the customer's shipping address. |
String | |
customer_info[shipping_address] |
The street address of the customer's shipping address.
See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP. |
string | YesFor Norway, you can only ship to a customer's legal address |
customer_info[shipping_postal] |
The postal code of the customer's shipping address. |
string | |
customer_info[shipping_region] |
The region of the customer's shipping address. |
string | |
customer_info[shipping_country] |
The country of the customer's shipping address as a 2 character ISO-3166 country code. |
[a-zA-Z]{2} | |
customer_info[shipping_city] |
The city of the customer's shipping address. |
string | |
customer_info[shipping_ref] | A reference that can be used to track the order | string | Optional. Can be used for B2B transactions (the customer_info[type]=business) |
customer_info[email] |
The customer's email address. |
string |
Yes for all Przelewy24 transactions Yes for NO and DE |
customer_info[customer_phone] |
The customer's telephone number, without spaces. This must include the country code. You can prefix the code with + (e.g. +446721846), or 00 (e.g. 00446721846), or omit the prefix (e.g. 446721846). |
string | |
customer_info[birthdate] |
The birth date of the customer Mandatory if your MCC code is 6012. |
Date (yyyy-mm-dd) | Yes, if your MCC code is 6012 |
customer_info[billing_lastname] |
The last name for the customer's billing address. Mandatory if your MCC code is 6012. |
String |
Yes, for DK, FI, and DE. |
customer_info[billing_firstname] |
The first name for the customer's billing address. |
String |
Yes, for DK, FI, and DE |
customer_info[billing_address] |
The street address of the customer's billing address. See the Notes on Addresses in Klarna Payments for more details on handling addresses for KP.
|
string |
Yes, for DK, FI, and DE |
customer_info[billing_city] |
The city of the customer's billing address. Mandatory for fraud detection. |
string | |
customer_info[billing_region] |
The region of the customer's billing address. Mandatory for fraud detection. |
string | |
customer_info[billing_postal] |
The postal code of the customer's billing address. Mandatory if your MCC code is 6012. Mandatory for fraud detection. |
string |
Yes |
customer_info[billing_country] |
The country of the customer's billing address as a 2 character ISO-3166 country code. Northern Ireland is an exception; see here. Mandatory for fraud detection. |
[a-zA-Z]{2} |
Yes |
customer_info[billing_att] | The name of the person/role who manages the billing for the company | string | |
customer_info[billing_ref] | A reference, for example, cost center, that can be used to track the purchase order | string | Optional. Can be used for B2B transactions (the customer_info[type]=business) |
customer_info[bank_phone] |
The phone number of the bank where the credit card was issued. |
String | |
customer_info[bank_name] | string | ||
customer_info[gender] |
Certain invoice payment providers require gender to be sent. Use this field to comply with that requirement. If this parameter is required by the provider, but not set in the method call, the customer is asked for this information on the payment page (callback_form). |
FMmalefemale |
|
customer_info[client_ip] |
The customer's IP address. Used for fraud detection. |
string | |
customer_info[client_session_id] |
A unique identifier of the customers session (eg. an md5 hash of the real session id). Used for fraud detection. |
string | |
customer_info[client_accept_language] |
The language setting of the customers browser. Used for fraud detection. |
string | |
customer_info[client_user_agent] |
The customers browser identification. Used for fraud detection. |
string | |
customer_info[client_forwarded_ip] |
The customers IP address as forwarded by transparent proxy. Used for fraud detection. |
string |

Parameter | Description | Type | Mandatory |
---|---|---|---|
orderLines | The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience. | Array |
Yes
|

Value |
Description |
Type |
Mandatory |
---|---|---|---|
description |
Description of an item. |
String (255) |
Yes |
itemId |
The item identification. Each itemId must be unique within an order. |
String (100) |
Yes |
quantity |
The quantity of the item. The value must be greater than zero. |
Decimal |
Yes |
unitPrice |
The unit price, excluding sales tax. The value must be greater than zero, unless the optional goodsType parameter is set to handling, in which case the field can be used to provide a discount. |
Decimal |
Yes |
taxPercent |
This is the tax percentage of the unit price. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one, the other is inferred, and rounding errors may occur. The taxAmount is used for the calculation, and taxPercent is printed on the invoice.
|
Decimal |
No |
taxAmount |
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 amount takes precedence. Send both the taxPercent and taxAmount parameters in the method call. If you provide only one of the taxPercent and taxAmount parameters, the other parameter is inferred, and rounding errors may occur.
The taxAmount is used for the calculation, and taxPercent is printed on the invoice. |
Decimal |
Yes |
unitCode |
The relevant measurement unit for the order line. For example, kg. |
String (50) |
|
discount |
The order line's discount in percent. |
Decimal |
|
goodsType |
The goods type of the order line - shipment| handling| item| digital| discount| gift_card| info| physical| sales_tax |
Yes |
|
imageUrl |
The full URL of the icon for the item |
String (255) |
|
productUrl | The full URL for the description of the item | String (255) |

- The OK page is not used, because customers have to sign a document after submitting the form.
- If a payment is initialized, but the customer leaves before the payment is completed, the payment will be in an incomplete state, and the TransactionStatus result is epayment_initialized.
- The notification page (callback_notification) is always called.
- The notification page (callback_notification) is, in most cases, triggered before the OK callback (callback:ok).
- The notification page (callback_notification) is used for chargebacks.
- The payment page (callback_form) is not shown to your customer.
- For more information about the callback pages in use, see the specifics for each credit card acquirer, Payment methods and providers.
- The notification page (callback_notification) is used when your customer doesn't return to the browser after a completed payment, and for chargebacks.
- The open page (callback_open) is used for pending transactions.
- The notification page (callback_notification) is used for transactions pending clarification.
Parameter |
Description |
Type |
Mandatory? |
---|---|---|---|
config[callback_form] | This is the callback form, or the payment page, and corresponds to the Callback url (form) setting in the Terminal settings. For more information, see Settings for the Payment Page (callback_form). For information about custom styling for the payment page, see Styling the payment page (callback_form). | String (Url) | No |
config[callback_ok] | This url is called when a payment succeeds, and corresponds to the Callback url (Ok) setting in Terminal settings. For more information, see Settings for the Payment OK page (callback_ok). | String (Url) | No |
config[callback_fail] | This url is called when a payment fails, and corresponds to the Callback url (Fail) setting in Terminal settings. For more information, see Settings for the fail page
(callback_fail). As Swish only allows one open payment at a time, the callback_fail form for Swish could offer some explanation, such as "The customer may have an open payment" or "The customer should check their Swish app for open payments". |
String (Url) | No |
config[callback_open] | This url is called when a payment returns with status Open, and corresponds to the Callback url (open) setting in Terminal settings. For more information, see Settings for the open page
(callback_open). For Klarna payments, the open page (callback_open) is used for pending transactions. |
String (Url) | No |
config[callback_notification] | This url is called when a notification is returned after the customer has left the payment flow, and corresponds to the Callback url (notification) setting in Terminal settings. For more information, see Payment Notification (callback_notification) For Klarna payments, the notification page (callback_notification) is used for transactions pending clarification. In some cases, the notification page can be called before the ok page or fail pages are called. |
String (Url) | No |
config[callback_verify_order] |
This URL is called just before the payment is processed.
If the payment fails, the first 255 characters of your response is shown as an error message to the customer. |
String (Url) | No |
config[callback_redirect] |
This url is called whenever the customer is redirected to a third party, and corresponds to the Callback url (redirect) setting in Terminal settings. For more information, see Settings for the redirect page (callback_redirect). |
String (Url) | No |

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).
Value | Description |
---|---|
Result |
The result of the request, for example:
|
PaymentRequestId | The payment request ID, used for subsequent processing. |
Url | The URL to redirect your customer to. |
DynamicJavascriptUrl | A url you can use in a Javascript to create an overlay payement page. For more information, see Styling a floating payment window. |


To fetch the complete cookie, including the session cookie, in php, you can use the following syntax:
$_SERVER['HTTP_COOKIE']
Sample of the XML response using GET
<?xml version="1.0"?> <APIResponse version="20170228"> <Header> <Date>2010-09-29T12:34:56+02:00</Date> <Path>API/createPaymentRequest</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <PaymentRequestId>2349494a-6adf-49f7-8096-2125a969e104</PaymentRequestId> <Url>https://gateway.altapaysecure.com/merchant.php/API/requestForm?pid=2349494a-6adf-49f7-8096-2125a969e104</Url> <DynamicJavascriptUrl>https://gateway.altapaysecure.com/eCommerce.php/API/embeddedPaymentWindow?pid=2349494a-6adf-49f7-8096-2125a969e104</DynamicJavascriptUrl> </Body> </APIResponse>

When you have redirected your customer to the URL provided by the call to createPaymentRequest, and your customer has successfully finished the payment, this XML is sent to the ok page (callback_ok). For more information, see Settings for the Payment OK page (callback_ok).
<?xml version="1.0"?> <APIResponse version="20170228"> <Header> <Date>2013-04-30T15:53:40+02:00</Date> <Path>API/reservation</Path> <ErrorCode>0</ErrorCode> <ErrorMessage></ErrorMessage> </Header> <Body> <Result>Success</Result> <Transactions> <Transaction> <TransactionId>7</TransactionId> <PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId> <AuthType>payment</AuthType> <CardStatus>InvalidLuhn</CardStatus> <CreditCardExpiry> <Year>2013</Year> <Month>01</Month> </CreditCardExpiry> <CreditCardToken>c63e01f71c0e7eced288f3a01aa94cce7d43a48f</CreditCardToken> <CreditCardMaskedPan>412012****4444</CreditCardMaskedPan> <ThreeDSecureResult>Not_Attempted</ThreeDSecureResult> <LiableForChargeback>Merchant</LiableForChargeback> <CVVCheckResult>Not_Applicable</CVVCheckResult> <BlacklistToken>12b14f9aa5fc7630c54ecc30eba0ff563f7671fb</BlacklistToken> <ShopOrderId>668850_orderId</ShopOrderId> <Shop>AltaPay Functional Test Shop</Shop> <Terminal>AltaPay Test Terminal</Terminal> <TransactionStatus>preauth</TransactionStatus> <ReasonCode>OPEN_WAITING_FOR_ACQUIRER</ReasonCode> <MerchantCurrency>978</MerchantCurrency> <MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha> <CardHolderCurrency>978</CardHolderCurrency> <CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha> <ReservedAmount>5.55</ReservedAmount> <CapturedAmount>0.00</CapturedAmount> <RefundedAmount>0.00</RefundedAmount> <RecurringDefaultAmount>0.00</RecurringDefaultAmount> <CreatedDate>2013-04-30 15:53:39</CreatedDate> <UpdatedDate>2013-04-30 15:53:40</UpdatedDate> <PaymentNature>CreditCard</PaymentNature> <PaymentSchemeName>Visa</PaymentSchemeName> <PaymentNatureService name="TestAcquirer"> <SupportsRefunds>true</SupportsRefunds> <SupportsRelease>true</SupportsRelease> <SupportsMultipleCaptures>true</SupportsMultipleCaptures> <SupportsMultipleRefunds>true</SupportsMultipleRefunds> </PaymentNatureService> <FraudRiskScore>5</FraudRiskScore> <FraudExplanation>For the test fraud service the risk score is always equal mod 101 of the created amount for the payment </FraudExplanation> <FraudRecommendation>Deny</FraudRecommendation> <ChargebackEvents/> <PaymentInfos> <PaymentInfo name="ka"><![CDATA[v1]]></PaymentInfo> <PaymentInfo name="kb"><![CDATA[v2]]></PaymentInfo> </PaymentInfos> <CustomerInfo/> <ReconciliationIdentifiers/> </Transaction> </Transactions> </Body> </APIResponse>

This example shows a call with only the required parameters, and the corresponding response.
Request
https://testgateway.altapaysecure.com/merchant/API/createPaymentRequest?terminal=MyTerminal&shop_orderid=1&amount=99.55¤cy=EUR
Response
<APIResponse version="20170228"> <Header> <Date>2017-10-23T11:30:16+02:00</Date> <Path>API/createPaymentRequest</Path> <ErrorCode>0</ErrorCode> <ErrorMessage/> </Header> <Body> <Result>Success</Result> <PaymentRequestId>4f81bc4c-3d51-403b-9cc5-118fced75ec5</PaymentRequestId> <Url> https://testgateway.altapaysecure.com/eCommerce/API/requestForm?pid=4f81bc4c-3d51-403b-9cc5-118fced75ec5 </Url> <DynamicJavascriptUrl> https://testgateway.altapaysecure.com/eCommerce/API/embeddedPaymentWindow?pid=4f81bc4c-3d51-403b-9cc5-118fced75ec5 </DynamicJavascriptUrl> </Body> </APIResponse>

Use the following to test credit card transactions. For test cases related to other payment methods, see Test case data.

API method | Scenario | Type | Trigger amount | Trigger card number |
---|---|---|---|---|
|
The reservation fails at the 3D Secure verification attempt. |
3DSecureFail | 4.66 |
|
|
The reservation returns a technical error at the 3D Secure verification attempt. |
3DSecureError | 4.67 |
|
|
The reservation succeeds after a successful 3D Secure verification. |
3DSecureWork | 4.68 |
|

API method | Scenario | Transaction status | Trigger card number |
---|---|---|---|
|
The reservation was initiated and a frictionless flow was triggered. |
TransactionStatus.ACCEPTED |
|
|
The reservation was initiated and a challenge flow was triggered. |
TransactionStatus.CHALLENGE |
|
|
The reservation was initiated and a decoupled challenge flow was triggered. |
TransactionStatus.DECOUPLED |
|
In order to trigger the Authenticated or Rejected result upon authentication, please do so by clicking one of the following buttons in the Mock ACS (testbank):

API method | Scenario | Type | Trigger amount | Trigger card number |
---|---|---|---|---|
|
The payment fails because it is declined by the bank. |
Failed | 5.66 |
|
|
The payment fails because of a technical error. |
Error | 5.67 |
|
|
The reservation succeeds after a successful 3D Secure verification. |
3DSecureWork | 5.68 |
|
|
The CVV code is correct. |
CVV Check Matched | 5.71 |
|
|
The CVV code is not correct. |
CVV Check MisMatched | 5.72 |
|
|
The CVV code is not applicable. |
CVV Check Not_Applicable | 5.73 |
|
|
The card verification fails because the card is declined. |
Failed | 16.66 |
|
|
The card verification fails because of a technical error. |
Error | 16.67 |
|

Use this test case data to test fraud check responses.
API method | Scenario | Error type | Amount | Card Number |
---|---|---|---|---|
|
Fraud check Accept | Accept | 101 |
|
|
Fraud check Challenge. | Challenge | 102 |
|
|
Fraud check Deny. | Deny |
110 |
|
|
Fraud check Unknown. | Unknown | Not possible |
|

Use this test case data to test the setup of recurring payments.
API method | Scenario | Error type | Amount | Card Number |
---|---|---|---|---|
|
Setting up a subscription fails because the payment is declined by the bank. | Failed | 14.66 |
|
|
Setting up a subscription fails because of a technical error. | Error | 14.67 |
|
|
Setting up a subscription and creating the first charge succeeds. |
Success | 13.68 |
|
|
Setting up a subscription works, but the first charge fails. | Failed | 13.69 |
|

Scenario | Error type | Amount | Card Number |
---|---|---|---|
Fails at credit or createPaymentRequest with the appropriate type set. | Failed | 9.66 |
|
Fails at credit or createPaymentRequest with the appropriate type set. | Error | 9.67 |
|

After you have redirected your customer to the Url, and the customer has completed the payment, a response is sent to the relevant callback page
If a payment was reserved, you can
- capture it using the captureReservation method.
- release it using the releaseReservation method.
If a payment was reserved and captured, you can:
- refund it using the refundCapturedReservation method.