iOS SDK

Installation

GoPay Tokenization SDK is available via Cocoapods on iOS.

Please follow the following steps to install the library to your app.

Step 1: Prepare the Podfile

//Add the following to your Podfile
target 'MyApp' do
  pod 'GopayCheckoutKit'
end

Step 2: Execute the Podfile

On your terminal, run pod install

// do pod install in your terminal
$ pod install

Step 3: Add the code to the AppDelegate

For Swift, you need to import GopayCheckoutKit in your AppDelegate.Swift File and every class where you plan to use the SDK method.
For Objective-C, you need to import GopayCheckoutKit.h in your AppDelegate.h and every class where you plan to use the SDK method.

Step 4: Setup app URL scheme

This step is needed to let the SDK go back to close the webview automatically and navigate to the previous screen. For example, your app URL scheme should be something like myapp://, all lowercase.

To set up your app URL scheme, you can choose to either:

Go to Project Settings -> Info, and add inside the URL Types section, a new URL scheme. Add something of the sort of myapp or any name you prefer, all lowercase.
Alternatively, you can also go to your info.plist file and paste the following code. You can rename the myapp value with your preferred name.

Initialization

To start using the SDK, you need to initialize the installed libraries. You can provide the following mandatory parameters:

Parameter Name	Explanation
merchant_id	This is your merchant ID. You can find this in your Midtrans dashboard
callback_url	This is the callback URL that will redirect back after webview is invoked
merchant_server_url	This is the address of the merchant server that you register to Midtrans

In your AppDelegate file, you need to set up the SDK within the application:didFinishLaunchingWithOptions: and application:openURL:method.

🚧
Important
For the callbackUrl parameter, please use your app URL scheme with this format myapp://app, by adding app to your app URL scheme, as shown in the code sample.

📘
Note
Ever since iOS 13, Apple introduced SceneDelegate**, So you’ll also need to add the handleCallbackUrl method of the sdk on the SceneDelegate file within the openURLContexts: method.

// setup your AppDelegate file

//init your sdk inside the didFinishLaunchingWithOptions: method
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
....

//implement sdk initialization
[GPYClient  initWithMerchantServerURL:MERCHANT_SERVER_URL  merchantId:MERCHANT_ID callbackUrl:@"myapp://app" isLoggingEnabled:NO];

// set the sdk handleCallbackUrl method inside the `openURL` method
(BOOL) application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{

//implement handleCallbackUrl method
[GPYClient handleCallbackUrl:url];
    return YES;
}

// setup your SceneDelegate File for ios 13
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts{

    //also add handleCallbackUrl method on SceneDelegate
    NSURL *url = URLContexts.allObjects.firstObject.URL;
    [GPYClient handleCallbackUrl:url];
}

For the isLoggingEnabled parameter, for security purposes, we encourage merchants to disable it (by giving false value) on production apps.

Account Linking On iOS

The following script can be used as an example for account linking on iOS


//Create GPYPartnerDetails object
GPYPartnerDetails *details = [[GPYPartnerDetails alloc]initWithPhoneNumber:phone countryCode:@"62"];

//Create metadata (optional)
NSDictionary *metadata = @{@"key1":@"value1",
                               @"key2":@"value2"};
             
// Use the initialized GPYClient object and pass the GPYPartnerDetails object as a parameter
 [GPYClient linkAccountWithPaymentType:@"gopay"
                          gopayPartnerDetails:details
                               viewController:self
                                     metadata:metadata
                                authorization:@"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
                                   completion:^(GPYLinkAccountResult * _Nullable result, NSError * _Nullable error) {
    if (result) {
        // do something
    } else{
       // error
    }
}];

For account linking call [GPYClient linkAccount] with parameter explained below.

Name	Type	Explanation	Required
PaymentType	String	Type of payment (eg:gopay)	Required
GPYPartnerDetails	Object	Contains partner information	Required
ViewController	Object	ViewController that called this method	Required
metadata	Object	Dictionary of String to String, put custom info for your usage	Optional
authorization	String	String value for authorization header. Recommended to use at least Basic Auth.	Optional

The GPYPartnerDetails object has the following properties that you need to fill up

Name	Type	Explanation	Required
phone	String	Phone number account to be linked	Required
countryCode	String	Country code related to account	Required

The GPYLinkAccountResult object will be received when the method calls succeeded. It has the following properties that you will require in other APIs

Name	Type	Explanation
accountID	String	Account ID to be used enquire account status, create a transaction and disable the account
accountStatus	String	Current account linking status. Possible values are ENABLED, PENDING, and DISABLED

The error object maps the error response from the Partner API. You can parse the message to identify the problem.

Account Status Enquiry On iOS

The following script can be used as an example for account status inquiry on Android :

//Account Status Enquiry On iOS

[GPYClient enquireAccountWithAccountID:ACCOUNT_ID authorization:@"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" completion:^(GPYAccountInfo * _Nullable result, NSError * _Nullable error) {
        if (result) {
            // Handle the account info of account enquiry
        } else{
            // Handle error
        }
    }];

For account enquiring call [GPYClient enquireAccount] with parameter explained below

Name	Type	Explanation	Required
accountId	String	GoPay account id	Required
authorization	String	String value for authorization header. Recommended to use at least Basic Auth.	Optional

The GPYAccountInfo object object will be received when the method calls succeeded. It has the following properties that is required in other APIs

Name	Type	Explanation
accountID	String	Account ID to be used to enquire account status, create a transaction and disable the account
accountStatus	String	Current account linking status. Possible values are ENABLED, PENDING and DISABLED
metadata	GPYAccountMetadata	List of available GPYPaymentOption objects

The GPYPaymentOption object has the following properties that you will require in other API

Name	Type	Explanation
name	String	Name of payment option
active	Boolean	Payment option status. True indicates active
token	String	Payment token to create transactions
balance	Amount	An object consisting of amount and currency

The error object maps the error response from the Partner API. You can parse the message to identify the problem.

Create Transaction On iOS

The following script can be used as an example for creating transactions on iOS :

//Create Transaction On iOS

GPYGopayDetails *gopayDetails = [[GPYGopayDetails alloc]initWithAccountID:ACCOUNT_ID paymentOptionToken:PAYMENT_OPTION_TOKEN];

GPYTransactionDetails *transDetails = [[GPYTransactionDetails alloc]initWithGrossAmount:@100 orderID:ORDER_ID currency:@"IDR"];

GPYItemDetails *itemDetails = [[GPYItemDetails alloc]initWithIthItemID:@"itemId1" name:@"one piece t-shirt" price:@100 quantity:@1 category:@"clothing"];

//Create metadata (optional)
NSDictionary *metadata = @{@"key1":@"value1",
                               @"key2":@"value2"};

[GPYClient createTransactionWithPaymentType:@"gopay"
                                     viewController:self
                                       gopayDetails:gopayDetails
                                 transactionDetails:transDetails 
                                    customerDetails:customerDetails
                                        itemDetails:@[itemDetails]
                                           metadata:self.metadata
                                      authorization:@"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" 
                                         completion:^(GPYTransactionResult * _Nullable result, NSError * _Nullable error) {
    if (result) {
        // Handle transaction finished
        // Result is available in the HTTP Notification not from SDK
    } else {
        // Handle error
    }
}];

For creating transaction call [GPYClient createTransaction] with parameter explained below

Name	Type	Explanation	Required
GPYGopayDetails	Object	Contains account_id, payment_option_token	Required
GPYTransactionDetails	Object	Contains order_id, gross_amount, and currency	Required
GPYCustomerDetails	Object	Filled with customer name and phone number	Required
GPYItemDetails	Object	List of Items each contains id, name, price, quantity, category	Optional
metadata	Object	Dictionary of String to String, put custom info for your usage	Optional
authorization	String	String value for authorization header. Recommended to use at least Basic Auth.	Optional

The GPYGopayDetails object has the following properties

Name	Type	Explanation	Required
accountId	String	GoPay accound id	Required
paymentOptionToken	String	Call enquire account to obtain	Required

The GPYTransactionDetails object has the following properties

Name	Type	Explanation	Required
orderId	String	Order id of transaction	Required
grossAmount	Long	Gross amount of transaction	Required
currency	String	Currency of transaction	Required

The GPYCustomerDetails object has the following properties

Name	Type	Explanation	Required
phone number	String	customer phone number	Required
name	String	customer name	Required

The GPYTransaction object has the following properties

Name	Type	Explanation
transactionID	String	The transaction ID recorded in the system.
transactionStatus	String	The transaction status. This will always return pending as the status will be sent via HTTP Notification.
orderID	String	The order ID set in the TransactionDetails passed into the create transaction API.
grossAmount	String	The transaction amount.
currency	String	The currency of the transaction.
paymentType	String	The payment option type used in the transaction.
transactionTime	String	The time of transaction.
fraudStatus	String	The fraud checking Status.

The error object maps the error response from the Partner API. You can parse the message to identify the problem.

Disable Account On iOS

The following script can be used as an example for disabling account on iOS :

//Create metadata (optional)
NSDictionary *metadata = @{@"key1":@"value1",
                               @"key2":@"value2"};
                               
//Disable Account On iOS

[GPYClient disableAccountWithAccountID:ACCOUNT_ID metadata:metadata authorization:@"Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" completion:^(GPYDisableAccountResult * _Nullable result, NSError * _Nullable error) {
        if (result) {
            // Handle response of disable account
        } else {
            // Handle error
        }
    }];

For disabling account Sdk will send following payload properties

Name	Type	Explanation	Required
accountId	String	Account id to be disabled	Required
metadata	Object	Dictionary of String to String, put custom info for your usage	Optional
authorization	String	String value for authorization header. Recommended to use at least Basic Auth.	Optional

The GPYDisableAccountResponse object has the following properties

Name	Type	Explanation
accountID	String	Account ID similar to what you use to disable account
accountStatus	String	Current account linking status. The result will always return DISABLED

The error object maps the error response from the Partner API. You can parse the message to identify the problem.