SumUp custom URL scheme

Using the custom SumUp URL scheme you can accept card payments from your iOS app or website through the SumUp iOS app.
To get started you will need to create a SumUp account and get an affiliate key in our Developer section.

If you are going to open the SumUp app from your own iOS app, SMPPaymentRequest is a convenient way to do so. See the sample app project for details and examples. You might also want to take a look at the SumUp iOS SDK to accept payments within your app.
If you are planning to open the SumUp app using a URL, please find the parameters below.

Base URL

sumupmerchant://pay/1.0

Mandatory query parameters

Key	Comment
amount	The amount to charge. Please use . as a decimal separator.
currency	The ISO 4217 code of currency to be charged. The currency needs to match the currency of the user that is logged into the SumUp app. For example EUR, GBP, BRL, CHF, PLN.
affiliate-key	Your affiliate key. It needs to be associated with the calling app’s bundle identifier.

Optional query parameters

Key	Comment
title	An optional title to be set on this transaction.
callbackfail	URL to be opened when the transaction fails. See Callback query parameters.
callbacksuccess	URL to be opened when the transaction succeeds. See Callback query parameters.
receipt-email	Prefills the email textfield when asking the customer whether he wants a receipts.
receipt-mobilephone	Prefills the phone number textfield when asking the customer whether he wants a receipts.
foreign-tx-id	An optional ID to be associated with this transaction. Please see our API documentation on how to retrieve a transaction using this ID. This ID has to be unique in the scope of a SumUp merchant account and its sub-accounts. It must not be longer than 128 characters and can only contain printable ASCII characters. Supported by SumUp app version 1.53 and later. Version 1.53.2 and later will append it to the callback URLs as a query parameter if provided.
skip-screen-success	To skip the screen shown at the end of a successful transaction, the skip-screen-success=true parameter can be used. When using the parameter your application is responsible for displaying the transaction result to the customer. In combination with the Receipts API your application can also send your own receipts, see API documentation for details. Please note success screens will still be shown when using the SumUp Air Lite readers. Supported by SumUp app version 1.69 and later.

Callback query parameters

After the payment has been executed the SumUp app will open the callbacksuccess URL if the payment succeeded and the callbackfail URL if it did not. We will append the following query parameters if applicable:

Key	Possible values	Comment
smp-status	success	The transaction has succeeded.
	failed	The transaction has failed.
	invalidstate	The transaction can not be accepted as the SumUp app is in an invalid state. Please ask the user to open the SumUp app and make sure he’s ready to accept payments.
smp-tx-code	TRANSACTION-CODE	The transaction code for this payment. Please see our API documentation to find out how to retreive details on this payment. Supported by SumUp app version 1.53 and later.
foreign-tx-id	YOUR-TX-ID	Only if provided. See Optional query parameters. Supported by SumUp app version 1.53.2 and later.

SMPPaymentRequest

If you are building your own iOS app you can use this class to conveniently open the SumUp app to accept a payment. It knows about all the URL parameters and makes accepting a payment as easy as:

SMPPaymentRequest *request;
NSDecimalNumber *amount = [NSDecimalNumber decimalNumberWithString:@"10.00"];

request = [SMPPaymentRequest paymentRequestWithAmount:amount
                                             currency:@"EUR"
                                                title:@"My title"
                                         affiliateKey:@"YOUR-AFFILIATE-KEY"];

[request setCallbackURLSuccess:[NSURL URLWithString:@"samplepaymentapp://"]];
[request setCallbackURLFailure:[NSURL URLWithString:@"samplepaymentapp://"]];

/* This will open the following URL
 * sumupmerchant://pay/1.0?amount=10.00&currency=EUR&affiliate-key=YOUR-AFFILIATE-KEY
 * &title=My%20title
 * &callbackfail=samplepaymentapp%3A%2F%2F
 * &callbacksuccess=samplepaymentapp%3A%2F%2F
 */

/* Optionally: Setting the option to skip success screens
 * to add skip-screen-success=true to the URL
 * Supported by SumUp app version 1.69 and later.
 * [request setSkipScreenOptions:SMPSkipScreenOptionSuccess];
 */

[request openSumUpMerchantApp];

Community

• Questions? Get in contact with our integration team by sending an email to [email protected].
• Found a bug? Open an issue. Please provide as much information as possible.