Description of service

The checkout API enables you as a merchant to accept payments online. Just create a session with the parameters you want, and then load the URL from the response in an iframe. The checkout UI will then handle the rest of the purchase and redirect the user to a URL of your choosing, and also notify you of the purchase through a callback.

See this link for a description of the flow.

API URL

Server Value
Stage https://api.stage.sweetpay.com
Production https://api.sweetpay.com

Requests

Create a session

Key Value
URL /v1/session/create
Method POST
Body CreateSessionRequest
Response ResponseEnvelope

CreateSessionRequest

Property Type Mandatory Description
country Country Yes The county for the customer.
merchantId String Yes The unique identifier for the merchant where the customer buys something.
transactions List of Transaction Conditional A list of all the items that should be bought and that should be invoiced once. This or subscriptions must be set.
subscriptions List of Subscription Conditional A list of all the subscriptions that should be subscribed to. This or transactions must be set.
redirectTarget RedirectTarget No Specifies how redirects should be handled. If no value is specified, the frame the checkout is loaded in itself will be redirected. If you load the checkout in an iframe, chances are that you want to set this parameter to TOP.
redirectOnFailureUrl String No Where the user is redirected to in the case of a failed payment.
redirectOnSuccessUrl String No Where the user is redirected to when a payment succeeds.
callbackOnFailureUrl String No URL that a callback will be sent to when a payment fails. The checkout will send a POST request to this URL (see CallbackEnvelope) after the a failed payment.
callbackOnSuccessUrl String No URL that a callback will be sent to when a payment succeeded. The checkout will send a POST request to this URL (see CallbackEnvelope) after a successful payment.
reservationCallbackUrl String No URL where reservation callbacks will be sent to for all reservations (if any) created through this session.
subscriptionCallbackUrl String No URL where subscription callbacks will be sent to for all subscriptions (if any) created through this session.
merchantTermsUrl String No The URL to your terms for the purchase. The link to these terms is usually included in the footer of the checkout.
language Language No The language the customer wants to use for the session. If omitted, the country default will be used.
merchantSessionId String No The session ID you can specify if you want to make sure that the same session isn't created twice. You can also specify this in the create session request if you want to specify your own session ID rather than saving the one generated by Sweetpay (see sessionId).
merchantCustomerId String No A merchant-unique identifier for the end customer. This value will override any other identification values. If omitted, Paylevo will generate a value.
phone String No The phone number for the end customer. If the value is not a valid phone number for the country, the value will be ignored. This is used for looking up the customer and authenticating.
email String No The email for the end customer. If the value is not a valid email address, the value will be ignored. This is used for looking up the customer. billingEmail should be used instead when entering invoicing details.
billingPhone String No The phone number to send invoices to. This will override phone for billing if both are submitted.
billingEmail String No The email to send invoices to. This will override email for billing if both are submitted.
billingName Name No The name of the customer to send the invoice to for cases where the name is already parted correctly. This will override name if both are submitted.
billingAddress Address No The address of the customer to send the invoice to for cases where the address is already parted correctly. This will override address for billing if both are submitted.
deliveryName Name No The name of the customer to send the merchandise to for cases where it differs from the invoice name and the name is already parted correctly. This will override name for delivery if both are submitted.
deliveryAddress Address No The address of the customer to send the merchandise to for cases where it differs from the invoice addresss, and the address is already parted correctly. This will override billingAddress if both are submitted.
merchantOrderId String No An ID of the order.
paymentMethod String No The payment method to use. If specified, the users will skip the step where they choose a payment method. Can currently only be INVOICE.
holdExecution Boolean No If the underlying transaction should held before execution. Will only work with transactions.
type String No Set to PERSON if the checkout should be for consumers and use ORGANISATION. Defaults to PERSON.

Envelopes

ResponseEnvelope

Property Type Description
status ApiStatus The status of the request. OK if everything went all right.
payload String Payload object.
version String The version of the checkout you are using.
createdAt Datetime The time the response was created in the server.

CallbackEnvelope

Property Type Description
createdAt Datetime When the event this callback concerns was created.
sentAt Datetime When the callback was sent.
callbackId Integer A unique ID, which you can use to make the callback handler idempotent. Having the callback handler idempotent is necessary in order to prevent your system from reading the same data twice (e.g. in the case of a timeout).
version String The version of the API used.
event String The event of the callback. Can either be CHECKOUT_SUCCEEDED or CHECKOUT_FAILED.
payload CallbackPayload The payload of the callback.

Objects

Customer

Property Type Description
phone String The phone for the customer, may be absent.
ssn String The ssn for the customer, may be absent.
org String The organisation number for the customer, may be absent.
email String The email for the customer, may be absent.
name Name The name for the customer.
address Address The address for the customer.

Transaction

Property Type Mandatory Description
currency Currency Yes The currency for the transaction.
amount Double Yes The total amount after discounts for the transaction, not per item in case of multiples. This is the amount that will be invoiced.
merchantTransactionId String No A merchant unique identifier for the transaction. This id may not be reused. If omitted, the field will be empty.
merchantItemId String No A merchant-unique identifier for the item the transaction is for. This may be reused. If omitted, the field will be empty.
rawAmount Double No The total amount for the transaction before discounts, if there is a difference. This will not be presented on the invoice, it's only for the checkout ui.
numberOfItems Double No The number of items the transaction is for. The amount is for all items, not per item. If omitted, 1 will be used. This field will be presented on the invoice as is, no verification will be done relative to amount and amountPerItem.
itemUnit String No The unit for the items bought in the transaction, could be “days” for services, “gallons” for fuel and such. This field will not be presented on the invoice, it's only for the checkout ui.
amountPerItem Double No How much each item costs, after discounts. This will be presented on the invoice, no calculations will be done to verify that it adds up to the total amount.
rawAmountPerItem Double No How much each item costs, before discounts. This will not be presented on the invoice, it's only for checkout ui. No calculations will be done to verify that it adds up to the total amount.
vat Double No The VAT percentage of the amount. If omitted, the default VAT rate for your account will be used. Provided that VAT is configured to be displayed on the invoice.
executedAt String No The time this transaction was executed. This field is only for presentation on the invoice if so configured. If omitted, the time of submission will be used.
comment String No The description of the transaction to put on the invoice. If omitted, a neutral (configurable) “Payment to {merchant}.” will be used. Where {merchant} is the merchant's company name. Can be used as an item name. It is preferable if the you set a value rather than omit it.\n

Subscription

Property Type Mandatory Description
currency Currency Yes The currency for the transaction.
amount Double Yes The total amount after discounts for the transaction, not per item in case of multiples. This is the amount that will be invoiced.
interval String Yes The interval of the invoice. Can be one of: MONTHLY, QUARTERLY and YEARLY. This indicates at which interval the subscription will be executed. If set to MONTHLY, the subscription will execute once per month, starting from startsAt+executionDelay.
startsAt Date Yes The date when the subscription should be started. If omitted, it will be set to today. If the date is in the past, it will be retroactively executed until it catches up. This means that if Subscription.interval is set to MONTHLY and you set this value to one month back in time, the customer will receive an invoice requiring them to pay for two months. Paylevo will decide at what time during the day to execute.
maxExecutions Integer No How many executions should be made for this subscription. If neither this or endsAt is set, the subscription will continue until explicitly cancelled. If both this and endsAt is set, the earliest of the two will decide when the subscription last executes. Therefore it is recommend to only use one of them to avoid confusion. Recommended.
endsAt Date No The date when the subscription should be ended. If this is at the same day as an execution, that day will not be executed. If both this and maxExecutions is set, the earliest of the two will decide when the subscription last executes. Therefore it is recommend to only use one of them to avoid confusion. It is recommended to use maxExecutions instead unless you have a special reason to use endsAt.
vat Double No The VAT percentage of the amount. If omitted, the default VAT rate for your account will be used. Provided that VAT is configured to be displayed on the invoice.
comment String No A comment on the invoice. Usually you use this parameter to specify what the customer is buying or for what period the invoice is for. There are three special templates you can specify: "{merchant}" (the name of the merchant registered at Sweetpay), "{starts}" (the beginning of the period the invoice concerns, will differ each invoice) and "{ends}" (the end of the period the invoice concerns, will differ each invoice).
merchantSubscriptionId String No The ID the merchant can specify to keep track of this subscription. Recommended.
merchantItemId String No The ID of the specific product (or item) this concerns. This is used for informational purpose only. Recommended.
executionDelay Integer No An Integer specifying how many days from startsAt the executions should be delayed. This postpones the execution each interval with the value set here. If this is set, all executions will be delayed with this amount. The first execution will thus occur at the date startsAt+executionDelay. If you don't have a special reason for using this, just ignore it. Defaults to 0.
numberOfItems Integer No How many items (products) there are of this kind, to be displayed on the invoice.
amountPerItem Integer No The amount per item displayed on the invoice. In the most common cases this is usually the amount divided by the numberOfItems.
itemUnit String No The unit of the item, to be displayed on the invoice. For example "KG".

Payload

Property Type Description
url String The URL to the checkout for the customer. To common use cases is to render it in an iframe or redirect the user to it.
sessionId String The ID of the checkout session. It is recommended that you store it to identify which session callbacks concern.

CallbackPayload

Property Type Description
sessionId String The ID of the checkout session.
merchantSessionId String The session id you can specify if you want to make sure that the same session isn't created twice. You can also set this in the CreateSessionRequest if you want to specify your own session ID rather than saving the one generated by Sweetpay (sessionId).
merchantCustomerId String The merchant's customer id. It is either autogenerated or specified when creating the session.
merchantOrderId String The unique (across every successful order) order ID.
executedAt Datetime When the payment went through or failed.
status ApiStatus The status of the callback.
currency Currency The currency of the transaction.
amount Double The amount paid.
reservationId Integers The ID of the underlying reservation. See the reservation API for more information about what you can do with this.
subscriptionIds List of integers The IDs of the created subscriptions. If you only create one subscription, the list will only contain one integer.
customer Customer The customer. Can be null.
billing Customer This represents the billing details. Can be null.

VerifyPurchaseReply

Property Type Description
comment String A comment which will be saved in SweetPay's logs. Just for information purpose.
status String You should set this to OK if you will accept this transaction. Everything else will tell SweetPay that the purchase shouldn't be verified.

Constants

RedirectTarget

Property Description
CLOSE Closes the window, if the checkout isn't loaded in an iframe.
TOP Tries to redirect the parent frame. If you are loading the checkout in an iframe, this will redirect the page which has embedded the iframe.