search

sumup / sumup-android-api

Other
19 stars 10 forks source link

readme

SumUp Android Payment API

I. Getting Started

II. How to call the Payment API

The sample app provided in this repository can be used as a reference.

Full SumUp API Documentation

API Helper

1. Add the repository to your gradle dependencies
allprojects {
   repositories {
      maven { url 'https://maven.sumup.com/releases' }
   }
}
2. Add the dependency to a module
compile 'com.sumup:merchant-api:1.4.0'
3. Make a payment
    SumUpPayment payment = SumUpPayment.builder()
            //mandatory parameters
            // Please go to https://me.sumup.com/developers to get your Affiliate Key by entering the application ID of your app. (e.g. com.sumup.sdksampleapp)
            .affiliateKey("YOUR_AFFILIATE_KEY")
            .total(new BigDecimal("1.23"))
            .currency(SumUpPayment.Currency.EUR)
            // optional: add details
            .title("Taxi Ride")
            .receiptEmail("customer@mail.com")
            .receiptSMS("+3531234567890")
            // optional: Add metadata
            .addAdditionalInfo("AccountId", "taxi0334")
            .addAdditionalInfo("From", "Paris")
            .addAdditionalInfo("To", "Berlin")
            //optional: foreign transaction ID, must be unique!
            .foreignTransactionId(UUID.randomUUID().toString())  // can not exceed 128 chars
            // optional: skip the success screen
        .skipSuccessScreen()
            .build();

    SumUpAPI.checkout(MainActivity.this, payment, 1);
4. Handle payment result
   @Override
   protected void onActivityResult(int requestCode, int resultCode, Intent data) {
      if (requestCode == 1 && data != null) {
         // Handle the response here
      }
   }

URI call

1. Provide a callback activity
    <activity
          android:name="com.example.URLResponseActivity"
          android:label="Payment Result">
            <intent-filter>
                <action android:name="android.intent.action.VIEW"/>
                <action android:name="com.example.URLResponseActivity"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <!-- Provide your own scheme here and reference it when you make a payment -->
                 <data
                   android:scheme="mycallbackscheme"
                   android:host="result"/>
            </intent-filter>
        </activity>
2. Make a payment
  Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(
                        "sumupmerchant://pay/1.0"
                                + "?affiliate-key="YOUR_AFFILIATE_KEY""
                                + "&app-id=com.example.myapp"
                                + "&total=1.23" // field available from App version 1.88.0 and above. Otherwise keep deprecated field "amount".
                                + "&currency=EUR"
                                + "&title=Taxi Ride"
                                + "&receipt-mobilephone=+3531234567890"
                                + "&receipt-email=customer@mail.com"
                                + "&foreign-tx-id=" + UUID.randomUUID().toString()
                                // optional: skip the success screen
                                + "&skip-screen-success=true"
                                + "&callback=mycallbackscheme://result"));

                startActivity(payIntent);

The result is received as a URI in the callback activity intent: 

Uri result = getIntent().getData()

Success:

mycallbackscheme://result?smp-status=success&smp-message=Transaction%20successful.&smp-receipt-sent=false&smp-tx-code=123ABC&foreign-tx-id=0558637a-b73c-43ad-b358-f93cb909251x

Failure:

mycallbackscheme://result?smp-status=failed&smp-failure-cause=transaction-failed&smp-message=Transaction%20failed.&smp-receipt-sent=false&smp-tx-code=123ABC&foreign-tx-id=05c14c86-a7a0-49c5-a1ec-acb168f5198x

Payment API - Web

Put a link onto your website

<a href="https://github.com/sumup/sumup-android-api/blob/master/sumupmerchant://pay/1.0?affiliate-key=7ca84f17-84a5-4140-8df6-6ebeed8540fc&app-id=com.example.myapp&total=1.23&currency=EUR&title=Taxi Ride&receipt-mobilephone=+3531234567890&receipt-email=customer@mail.com&callback=http://example.com/myapp/mycallback">Start SumUp Payment</a>

Note that field total is available from App version 1.88.0 and above. Keep deprecated field amount if still supporting older versions of the SumUp App.

Make sure that the callback URL you provide is correct and controlled by you.

Success:

?smp-status=success&smp-message=Transaction%20successful.&smp-receipt-sent=false&smp-tx-code=123ABC

Failure:

?smp-status=failed&smp-failure-cause=transaction-failed&smp-message=Transaction%20failed.&smp-receipt-sent=false&smp-tx-code=123ABC

III. Additional features

1. Response fields

a) With the API Helper

Several response flags are available when the callback activity is called :

The response flags are provided within the Bundle that is passed back to the callback activity.

    int resultCode = getIntent().getExtras()getInt(SumUpAPI.Response.RESULT_CODE);
b) With the URI call / Payment API - Web

2. Additional checkout parameters

Transaction identifier

The foreignTransactionID identifier will be associated with the transaction and can be used to retrieve details related to the transaction. See API documentation for details. Please make sure that this ID is unique within the scope of the SumUp merchant account and sub-accounts. It must not be longer than 128 characters. The foreignTransactionID is available when the callback activity is called: SumUpAPI.Param.FOREIGN_TRANSACTION_ID

Skip success screen

To skip the screen shown at the end of a successful transaction, the skipSuccessScreen 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.

Community