PayWithMyBank Recurring Payment

Definition: POST /v1/payments/recurrent

A recurring payment is created in the same manner a one-off payment is created. In addition, you need to send the PreapprovalID (the PreapprovalID received when you created/opened a preapproval) and the information specific to each payment method.

For PayWithMyBank (58), you need to send the PreapprovalID (the PreapprovalID received when you created/opened a preapproval) and the Amount to be captured:

Request:

POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk={
 "Payment": {
   "PreapprovalID": 19800,
   "MerchantTransactionID": "s2ptest_h-1",
   "Amount": 20,
   "Currency": "USD",
   "MethodID": 58
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4722746,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190729142257",
        "MerchantTransactionID": "s2ptest_h-1",
        "OriginatorTransactionID": null,
        "Amount": "20",
        "Currency": "USD",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "",
        "MethodID": 58,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 19800,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "Fraud": null,
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

Please be aware that the final status of the payment can be received in up to 3 business days depending on the customer’s Bank used!

PayWithMyBank Close a Preapproval

Definition: DELETE /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

To close a preapproval, you must send a DELETE action for an existing preapproval object.

Checkout the below example to close a preapproval for PayWithMyBank (58):

Request:

DELETE https://paytest.smart2pay.com/v1/preapprovals/19800
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Update: 1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 4,
            "Info": "ClosedByCustomer",
            "Reasons": null
        },
        "RedirectURL": null,
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

PayWithMyBank Change a Preapproval

Definition: PATCH /v1/preapprovals/{id}

Where:
  • {id} – GlobalPay Preapproval ID

You can change the attributes of an already created preapproval by applying a PATCH.

Checkout the below example to change a preapproval for PayWithMyBank (58):

Request:

PATCH https://paytest.smart2pay.com/v1/preapprovals/19800
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_h-1",
   "PreapprovedMaximumAmount": 20,
   "Currency": "USD",
   "Description": "Update: 1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 58,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "US"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "Update: 1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/PWMB/Landing/PreapprovalLanding.aspx?ID=15352&Hash=8FCF71570B0E7CE025C33B27E34F4493",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

PayWithMyBank Preapproval Notification

Upon successful approval, we will notify you about the new status of the preapproval to the URL you setup in the Merchant Dashboard.

You need to respond with HTTP Status 204 (No Content)!

Preapproval notification format for PayWithMyBank:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
"Preapproval": {
  "ID": 19800,
  "Created": "20190729134913",
  "MethodID": 58,
  "SiteID": 30201,
  "MerchantPreapprovalID": "s2ptest_h-1",
  "RecurringPeriod": 0,
  "PreapprovedMaximumAmount": "20",
  "Currency": null,
  "ReturnURL": "http://demo.smart2pay.com/redirect.php",
  "Description": "1 year subscription",
  "Customer": {
    "ID": 2625948,
    "MerchantCustomerID": null,
    "Email": "jdoe@gmail.com",
    "FirstName": "John",
    "LastName": "Doe",
    "Gender": null,
    "SocialSecurityNumber": null,
    "Phone": null,
    "Company": null,
    "DateOfBirth": null
  },
  "BillingAddress": {
    "ID": 520,
    "City": null,
    "ZipCode": null,
    "State": null,
    "Street": null,
    "StreetNumber": null,
    "HouseNumber": null,
    "HouseExtension": null,
    "Country": "US"
  },
  "Status": {
    "ID": 2,
    "Info": null,
    "Reasons": null
  },
  "RedirectURL": null,
  "MethodOptionID": 0,
  "PreapprovedFrequency": null,
  "MandateReference": null,
  "Details": null
  }
}

Response:

204 No Content

The message contains a Preapproval object with an updated Status, which can have the following meanings:

PREAPPROVAL STATUS
ID Info Description
1 Pending The customer needs to confirm the preapproval
2 Open The customer confirmed and you can use the preapproval to initiate recurring payments
4 ClosedByCustomer The preapproval is closed and can no longer be used to initiate recurring payments

PayWithMyBank Preapproval Request

Definition: POST /v1/preapprovals

To initiate a preapproval, you must create a preapproval object. The parameters of the preapproval are sent in the message body as a JSON object. See below an example of a preapproval request for PayWithMyBank (58).

With PayWithMyBank, you can create preapprovals that can allow you to form subsequent recurrent payments. This is the most flexible type and allows the merchant to fully control when to initiate the money transfer(s) between the end user’s account and the merchant’s account (credits or debits). The Preapproval call basically creates a transaction representing the end user’s authorization to use their account for payments on the terms set in the request.

A transaction ID is returned to the merchant within the return URL in the Preapproval response/notification. The merchant must store this transaction ID in the end user’s payment profile to allow future recurrent requests. The amount sent on the initial call defines the maximum aggregate amount that can be captured from the end user’s account across all recurrent calls. A zero-amount value on the Preapproval call removes this upper bound limit. With that setting, the merchant can enable open-ended recurrent scenarios.

For PayWithMyBank preapproval requests CustomerName and CustomerEmail parameters are mandatory in the initial payment request.

Request:

POST https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_h-1",
   "PreapprovedMaximumAmount": 20,
   "Currency": "USD",
   "Description": "1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 58,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "US"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 19800,
        "Created": "20190729134913",
        "MethodID": 58,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h-1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": "20",
        "Currency": "USD",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "1 year subscription",
        "Customer": {
            "ID": 2625948,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 520,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "US"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/PWMB/Landing/PreapprovalLanding.aspx?ID=15351&Hash=CD3F91C3DF49E901E91240FA42D89A64",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

GlobalPay Status Codes

List of transaction status IDs
Status ID Name Description Final Status Applicable for
1 Open The transaction is initiated in our system. No Payments / Refunds / Payouts
2 Success The transaction is successful. Yes Payments / Refunds / Payouts
3 Cancelled The payment was cancelled. The payments that can be cancelled are the payments with “Authorized” status or the payments that are cancelled by the customer on the form. Yes Payments
4 Failed The transaction has failed. Yes Payments / Refunds / Payouts
5 Expired The time period the customer had for completing the payment has expired. Yes Payments
9 Authorized The payment was successfully authorized. In the initial request the Capture parameter is sent to false so the responsibility of the capturing the payment is on the merchants side.
The goods can be delivered.
No Payments
13 CaptureRequested The payment was successfully authorized and the capture request was also sent to the provider.
The goods can be delivered.
No Payments
14 Exception The transaction needs manual review from Smart2Pay. No Payments
15 CancelRequested The cancel request has been sent. No Payments
16 Reversed The authorization has been reversed (the money were credited back to the customer account). Yes Payments
19 Disputed The payment is disputed by the customer. No Payments
26 Chargedback The cardholder has won the dispute and has received the money back. Yes Payments
35 PartiallyCaptured The payment is partially captured. Yes Payments

PSD2 and Strong Customer Authentication (SCA)

The Second Payment Services Directive (PSD2), a set of laws and regulations for payment services in the European Union (EU) and the European Economic Area (EEA), has come with a lot of implications for marketplace business models already, and it will expand further more on all companies in Europe that deal with payments, ranging from how to regulate the emergence of Third Party Providers (TPPs) to the need for strong customer authentication (SCA).

Strong Customer Authentication (SCA) will come into effect on 14 September 2019, so there is little time for merchants to start updating their integration to prepare for it. Transactions that don’t follow the new authentication guidelines may be declined by the banks.

SCA requires merchants to integrate into the checkout flow a two-factor authentication that is based on the use of two or more elements categorised as:

  • knowledge (something only the user knows, i.e password);
  • possession (something only the user possesses: i.e.,phone, token, certificate tec.);
  • inherence (something the user is: i.e. fingerprint, Face ID).

For an authentication to meet the criteria of the PSD2, it must combine at least 2 of these 3 factors. To strongly authenticate an online payment, for example, consumers will be required to use their phone (something you own) and authenticate via fingerprint (something you are).

As of September 14, the credit card number alone will no longer be considered as a valid authentication method and additional factors that meet the requirements of PSD2, such as biometric data, need to be added in the authentication process.

The 3D Secure version 1.0 authentication method used for credit card payments is being updated to version 2.0, which is the best measure to meet the above compliance criteria.

The Strong Customer Authentication (SCA) has to be applied when all of the conditions below are met:

  • The business is based in the European Economic Area (EEA);
  • The customers are from EEA area;
  • The payment is initiated online by the customer.

Apart from these cases there are a few exemptions to SCA, but keep in mind that banks can choose to not honor these exemptions and you need to be prepared to handle a SCA challenge even if the transactions has been submitted under one of the exemptions.

SCA exemptions:

  1. Low Value
  2. Low Risk / TRA
  3. Recurring
  4. Trusted Beneficiaries
  5. MIT
  6. Secure Corporate payments

1. Low value: Small amounts less than 30 EUR

For a transaction of less than 30 EUR and up to 100 EUR accumulated or up to 5 transactions since the last SCA. Beyond 100 EUR or beyond 5 unauthenticated transactions, a new SCA is required. Keep in mind that since the information needed to validate these stipulations is only available to the issuing bank, you will still need to confirm if SCA is required on all transactions that might fall into this exemption category.

2. TRA – Transactional Risk Analysis

SCA can be deactivated for online payments between €30 and €500, depending on the payment providers fraud rates (see table below). There are no low-risk exemptions for transactions over €500. Merchants have to rely on a payment service provider (e.g. an acquirer) to act upon their request. In addition, the test to trigger the exemption rests with whether the PSP satisfies the prescribed conditions, not the merchants themselves. Smart2Pay keeps a very low fraud rate by using state of the art anti-fraud solutions such as RedShield, Machine Learning algorithms and by working with low risk acquiring banks which have very good fraud scores.

Adding additional information in the payment request will maximize the probability of getting the exemption by Issuers. The chargeback liability shifts to the issuer as well.

Regulatory Technical Standards (RTS), that payment providers need to take into account through real-time risk analysis, covers the following:

  • abnormal spending or behavioral pattern of the payer;
  • unusual information about the payer’s device/software access;
  • malware infection in any session of the authentication procedure;
  • known fraud scenario in the provision of payment services;
  • abnormal location of the payer;
  • high-risk location of the payee.

The fraud rate limits for payment providers are being applied as follows:

Fraud rate and amount limits
Fraud transaction rate Amount limits
Up to 0.01% Up to €500
Up to 0.06% Up to €250
Up to 0.13% Up to €100

3. Recurring transactions / Subscriptions of the same amount for the same beneficiary

SCA authentication is required only for the first transaction of a subscription or recurring billing service. The following transactions having the same amount with the same online seller don’t require a new SCA. By using Smart2Pay recurring transactions API you can apply this exemption as well.

4. Payment to a trusted beneficiary

Customers can add their preferred online sellers to a list of trusted beneficiaries held by the issuing bank, so that they don’t required to authenticate for each new payment. Please instruct your customers if possible to add your business to the white-list at their bank.

5. Merchant Initiated Transaction (MIT)

MITs are payment transactions that are not initiated by the payer but by the payee only and are not subject to strong customer authentication (SCA) to the extent that these transactions are initiated without any interaction or involvement of the payer. MIT transactions are subjected to SCA except when a mandate is signed by the client. For example, SEPA Direct Debits are initiated by the merchant but have a direct debit mandate signed by the end customer. Thus, SCA is not applicable in this case and there are no restrictions to the frequency or the amount (obtained scheme transaction identifier needs to be provided for use in the subsequent transactions).

Adjustment of initial Authorisation allows merchants to increase or decrease the authorised amount after the initial authorisation has taken place is also MIT. This enables tipping.

Please check out our page again soon where we will keep you posted on any updates regarding 3D Secure version 2.0.

Payout Notification

We will notify you about the new status of the payout to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

You need to respond with HTTP code 204 (No Content)!

Payout notification format:

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "ID": 376,
    "Created": "20190507131247",
    "MerchantTransactionID": "s2ptest_j1",
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "",
    "SiteID": 30201,
    "Details": null,
    "Customer": null,
    "BillingAddress": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    }
  }
}

Response:

204 No Content

Get information on a specific Payout

You can get information about a payout by using GET HTTP request.

Definition: GET /v1/payouts/{id}

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://paytest.smart2pay.com/v1/payouts/376
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payout": {
        "ID": 376,
        "Created": "20190507131247",
        "MerchantTransactionID": "s2ptest_j1",
        "Amount": "1000",
        "Currency": "EUR",
        "Description": null,
        "SiteID": 30201,
        "Details": null,
        "Customer": {
            "ID": 335,
            "MerchantCustomerID": "0125",
            "Email": "youremail@email.com",
            "FirstName": "Example",
            "LastName": "Test",
            "Gender": "F",
            "SocialSecurityNumber": "ABCDE1234F",
            "Phone": "0765260000",
            "Company": "S2P",
            "DateOfBirth": "19800519"
        },
        "BillingAddress": null,
        "Status": {
            "ID": 2,
            "Info": "Success",
            "Reasons": null
        }
    }
}

Create a Payout

Definition: POST /v1/payouts

To initiate a payout, you must create a payout object. The parameters of the payout are sent in the message body as a JSON object.

The payment methods that support payouts are: Trustly (29) and Qiwi (1003).

  • For Trustly Payouts(29) you need to send in the request the Customer Bank Account ID parameter.

    A 201 HTTP response (Created) is returned if the payout was correctly initialized.

    Request:

    POST https://paytest.smart2pay.com/v1/payouts
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payout": {
        "MerchantTransactionID": "s2ptest_j1",
        "Amount": 1000,
        "Currency": "EUR",      
        "MethodID": 29,
        "Customer": {    
          "Email": "youremail@email.com"   
        },
        "Details":{
          "CustomerBankAccountID": "3541977722"}
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
        "Payout": {
            "ID": 376,
            "Created": "20190507131247",
            "MerchantTransactionID": "s2ptest_j1",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": null,
            "SiteID": 30201,
            "Details": {
                "CustomerBankAccountID": "3541977722"
            },
            "Customer": {
                "ID": 335,
                "MerchantCustomerID": null,
                "Email": "youremail@email.com",
                "FirstName": null,
                "LastName": null,
                "Gender": null,
                "SocialSecurityNumber": null,
                "Phone": null,
                "Company": null,
                "DateOfBirth": null
            },
            "BillingAddress": null,
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": null
            }
        }
    }
  • For Qiwi Payouts all you need is the customer’s phone number and no restrictions regarding an initial payment with the same phone number. This option applies only for customers that have an active Qiwi Wallet Account.

    Request:

    POST https://paytest.smart2pay.com/v1/payouts
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payout": {
        "MerchantTransactionID": "s2ptest_j12",
        "Amount": 10,
        "Currency": "USD",      
        "MethodID": 1003,
        
        "Customer": {    
         "Phone":"+79257836967" 
        }    
      }
    }

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "Payout": {
        "ID": 511,
        "Created": "20190603111300",
        "MerchantTransactionID": "s2ptest_j12",
        "Amount": "10",
        "Currency": "USD",
        "Description": null,
        "SiteID": 30201,
        "Details": null,
        "Customer": {
          "ID": 207203,
          "MerchantCustomerID": null,
          "Email": null,
          "FirstName": null,
          "LastName": null,
          "Gender": null,
          "SocialSecurityNumber": null,
          "Phone": "+79257836967",
          "Company": null,
          "DateOfBirth": null
          },
        "BillingAddress": null,
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": null
        }
      }
    }

For Qiwi Payouts to be successful the phone number used in the request has to be linked with a Qiwi wallet account, otherwise the payout request will be rejected with the below message:

Request:

POST https://paytest.smart2pay.com/v1/payouts
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "MerchantTransactionID": "s2ptest_j13",
    "Amount": 10,
    "Currency": "USD",      
    "MethodID": 1003,
    
    "Customer": {    
     "Phone":"+79257836965" 
    }    
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 513,
    "Created": "20190603114013",
    "MerchantTransactionID": "s2ptest_j13",
    "Amount": "10",
    "Currency": "USD",
    "Description": null,
    "SiteID": 30201,
    "Details": null,
    "Customer": {
      "ID": 212321,
      "MerchantCustomerID": null,
      "Email": null,
      "FirstName": null,
      "LastName": null,
      "Gender": null,
      "SocialSecurityNumber": null,
      "Phone": "+79257836965",
      "Company": null,
      "DateOfBirth": null
      },
    "BillingAddress": null,
    "Status": {
      "ID": 4,
      "Info": "Failed",
      "Reasons": [
        {
          "Code": "278",
          "Info": "User does not exists"
        }
      ]
    }
  }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

POST https://paytest.smart2pay.com/v1/payouts
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payout": {
    "MerchantTransactionID": "s2ptest_j2",
    "Amount": 1000,
    "Currency": "EUR",      
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "Details":{
      "CustomerBankAccountID": "3541977722"}
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Payout": {
        "ID": 0,
        "Created": null,
        "MerchantTransactionID": "s2ptest_j2",
        "Amount": "1000",
        "Currency": null,
        "Description": null,
        "SiteID": 30201,
        "Details": {
            "CustomerBankAccountID": "3541977722"
        },
        "Customer": {
            "MerchantCustomerID": null,
            "Email": "youremail@email.com",
            "FirstName": null,
            "LastName": null,
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": null,
        "Status": {
            "ID": null,
            "Info": null,
            "Reasons": [
                {
                    "Code": "1",
                    "Info": "Missing parameter - MethodID"
                }
            ]
        }
    }
}

Disputes Details

Go to Disputes tab from the dashboard and use the search filters to find a specific dispute. After you have found the transaction you have been looking for, using the search filters, just double click on it to see specific details of that dispute.

A new window will open containing the general details for that Dispute ID and also providing details about specific sections, like: Reporting, Reason Codes and Initial Payment.

The dashboard Dispute Details allows the user to always find specific information in order to be informed and keep track of his day-to-day operations and disputes.

General provides detailed information for the following fields: ID of the dispute, Initial Payment ID, Input Date Time, Merchant ID, Merchant Site ID, Method ID, Merchant Alias, Merchant Site Alias, Method Name, Amount, Currency and Status.

32

Reporting provides detailed information for the following fields: Notification Date Time and Last Notified Status.

32

Reason Codes provides detailed information for the following fields: Reason Code and Reason.

32

Initial payment provides detailed information for the following fields: ID, Merchant Transaction ID, Originator Transaction ID, Input Date Time, Amount, Currency, Status, Available Amount, Method ID, Method Name and Country.

32

Disputes List

Access the Disputes tab in order to see and verify your disputes. Here you will find a complete list of all of your payments that are disputed by the customer. You have the possibility to search for a specific dispute using different search filters, to see the details of the disputes, and to export your disputes into an Excel file.

32

Search filters

When you access the Disputes tab, the Search Filters section is expanded. In order to collapse it just click the arrow on the right of the screen.

You can search disputes by ID (the dispute id in the GlobalPay system), Initial Payment ID, Method, Amount, Currency, Status, Interval (from – to) and Site Alias.

32

Disputes Details

After you have found the transaction you’ve been looking for, using the search filters, just click on it to see the specific details of that dispute.

A new window will open containing the general details for that disputes ID and also providing details about specific sections, like: Reporting, Reason Codes, Initial Payment.

66

Export transactions

The list of disputes can be exported (filtered or not) to an .xls file. Click on the Export to EXCEL button at the end of the list of payments.

32

The downloaded file contains the following information: ID, Input Date/Time, Payment ID, Originator Transaction ID, Amount, Currency, Status, Status ID, Method, Method ID, Site ID, Site Alias, Reason Code and Reason.

32

Preapprovals Details

Go to Preapprovals tab from the dashboard and use the search filters to find a specific preapproval. After you have found the transaction you have been looking for, using the search filters, just double click on it to see specific details of that preapproval.

A new window will open containing the general details for that Preapproval ID and also providing details about all the payments associated with that preapproval.

The dashboard Preapprovals Details allows the user to always find specific information in order to be informed and keep track of his day-to-day operations and preapprovals.

General provides detailed information for the following fields: ID of the preapproval, Merchant Preapproval ID, Status, Method ID,Site ID, Site Alias, Merchant Alias, Merchant ID, Input Date Time, Description, Details, Maximum Amount, Currency, Method Option ID, Frequency, Mandate Reference.

32

Payments contains a list of all the payments associated with that preapproval and provides detailed information for the payment’s following fields: Payment ID, Merchant Transaction ID, Amount, Currency, Status, Method, Root Provider Transaction ID, Site, Country.

32

Preapprovals List

Access the Preapprovals tab in order to see and verify your preapprovals. Here you will find a complete list of all of your preapprovals. You have the possibility to search for a specific preapproval using different search filters, to see the details of the preapproval and all the payments associated with the preapproval.

32

Search filters

When you access the Preapprovals tab, the Search Filters section is expanded. In order to collapse it just click the arrow on the right of the screen.

You can search preapprovals by ID (the preapproval id in the GlobalPay system, a unique number that identifies the preapproval in the GlobalPay system; you will need to store this id in order to initiate recurring payments.), Merchant Preapproval ID (the preapproval id in your system), Status, Method, Site Alias and Interval (from – to).

32

Preapprovals Details

After you have found the transaction you’ve been looking for, using the search filters, just click on it to see the specific details of that preapproval.

A new window will open containing the general details for that Preapproval ID and also providing details about all the payments associated with that preapproval.

32

Capture scenarios for PostFinance Card

 

Capture Scenarios Response Status Description Notification Status Description

The transaction has been fully captured.

Only payments with “Authorized” status (9) can be captured.
Intermediary Status: 13 Capture Requested Final Notification Status: 2 Success

The payment has been partially captured.

Only payments with “Authorized” status can be partially captured. The payment has been sent out to be partially captured, but the payment gateway has not yet confirmed that the payment is successful.
Intermediary Status: 13 Capture Requested Final Notification Status: 35 Partially Captured
Capture Failed Scenarios Return Code Description

Retry Capture

This happens when the request timeouts at Provider; a new capture request has to be initiated.
Return Code: 157 Unable to capture transaction

The transaction could not be captured.

The transaction is not in an Authorized status (it has already been fully Captured or Partially Captured).
Return Code: 17 Payment is invalid

For a complete list of all the possible Return Code IDs go to our section GlobalPay Return Codes.

See the request – response examples for the above possible scenarios:

  • Success Status

    A payment can only be captured if it has an Authorized status. Once the payment has an Authorized status (9), you can capture either the full amount or a partial amount of the initial authorized amount for the transaction.

    A 200 HTTP response (OK) is returned if the request was completed successfully.

    Full capture means you capture the entire authorized amount for the initial transaction.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4424180/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4424180,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190320121124",
            "MerchantTransactionID": "PostFinance_55EMI",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190320121338",
            "Customer": null,
            "BillingAddress": {
                "ID": 7808,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "CH"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": null
            },
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
        }
    }
    

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
    
    {
      "Payment": {
        "ID": 4424180,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190320121124",
        "MerchantTransactionID": "PostFinance_55EMI",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "CHF",
        "CapturedAmount": "1000",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "",
        "MethodID": 1129,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30151,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
          "ID": 7808,
          "City": null,
          "ZipCode": null,
          "State": null,
          "Street": null,
          "StreetNumber": null,
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "CH"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 10,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
      }
    }
    
  • Partially Captured Status

    Partial capture means you have the possibility to capture a smaller amount than the one from the initial authorized transaction. Partial capture is used when you have sent at least part of the order to the consumer and want to capture the amount for the item(s) that have been shipped.

    You can perform only one partial capture for an authorized transaction with the limitation that the amount of the partial capture to be smaller or equal than the initial authorized amount.

    Specify only the captured amount parameter in the query string, in order to partially capture the payment, like in the below example:

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4424180/capture?amount=500
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

    Response:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4424180,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190320121124",
            "MerchantTransactionID": "PostFinance_55EMI",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190320121338",
            "Customer": null,
            "BillingAddress": {
                "ID": 7808,
                "City": null,
                "ZipCode": null,
                "State": null,
                "Street": null,
                "StreetNumber": null,
                "HouseNumber": null,
                "HouseExtension": null,
                "Country": "CH"
            },
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": null
            },
            "MethodTransactionID": null,
            "TokenLifetime": 10,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
        }
    }
    

    We will notify you about the new status of the payment to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

    You need to respond with HTTP code 204 (No Content)!

    Payment notification format:

    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk={
      "Payment": {
        "ID": 4424180,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190320121124",
        "MerchantTransactionID": "PostFinance_55EMI",
        "OriginatorTransactionID": null,
        "Amount": "1000",
        "Currency": "CHF",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "",
        "MethodID": 1129,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30151,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
          "ID": 7808,
          "City": null,
          "ZipCode": null,
          "State": null,
          "Street": null,
          "StreetNumber": null,
          "HouseNumber": null,
          "HouseExtension": null,
          "Country": "CH"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
          "ID": 35,
          "Info": "PartiallyCaptured",
          "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 10,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=FFABC0234D73F9D23DAC72E1DFC52E61.4424180"
      }
    }
    
  • Return Code: 157 – Unable to capture transaction

    The transaction could not be captured. Retry Capture. This happens when the request timeouts at Provider.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4426277/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    
    {
        "Payment": {
            "ID": 4426277,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190322135942",
            "MerchantTransactionID": "s2ptest_a3",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "CHF",
            "CapturedAmount": null,
            "ReturnURL": "http://demo.smart2pay.com/redirect.php",
            "Description": "test test",
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": "20190322140025",
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 9,
                "Info": "Authorized",
                "Reasons": [
                    {
                        "Code": "157",
                        "Info": "Unable to capture transaction"
                    }
                ]
            },
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }
  • Return Code: 17 – Payment is invalid

    The transaction could not be captured. The transaction is not in an Authorized status. You can receive this response when the payment you want to Capture is not Authorized or when the payment has already been Captured.

    Request:

    POST https://paytest.smart2pay.com/v1/payments/4426219/capture
    Authorization: Basic MzAxNTE6V05ydTJ5WnJpR2RtNVVMZWt4dFM4cHprUXNRSmdYYTZBZnlnT3FXZXcvNlRBYzNYK1A=

    Response:

    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8{
        "Payment": {
            "ID": 4426219,
            "SkinID": null,
            "ClientIP": null,
            "Created": "20190322125640",
            "MerchantTransactionID": null,
            "OriginatorTransactionID": null,
            "Amount": null,
            "Currency": null,
            "CapturedAmount": null,
            "ReturnURL": null,
            "Description": null,
            "MethodID": 1129,
            "MethodOptionID": null,
            "IncludeMethodIDs": null,
            "ExcludeMethodIDs": null,
            "PrioritizeMethodIDs": null,
            "SiteID": 30151,
            "NotificationDateTime": null,
            "Customer": null,
            "BillingAddress": null,
            "ShippingAddress": null,
            "Articles": null,
            "Details": null,
            "ReferenceDetails": null,
            "CustomParameters": null,
            "PreapprovalID": null,
            "Status": {
                "ID": 13,
                "Info": "CaptureRequested",
                "Reasons": [
                    {
                        "Code": "17",
                        "Info": "Payment is invalid - 4426219"
                    }
                ]
            },
            "MethodTransactionID": null,
            "TokenLifetime": null,
            "Capture": null,
            "PreapprovalDetails": null,
            "RedirectURL": null
        }
    }

PayTM Test Data

For PayTM payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PayTM – Test Payment Flow

  1. The customer enters his Email Address, Name, Permanent account number (PAN) and his address including Street, Street Number and City. Please note that for India the CustomerSocialSecurityNumber parameter consists of PAN. For more information about the PAN please click here.

    1 Enter customer details

  2. The customer logs in to his account by entering his Customer ID and password. For test purposes, enter any Customer ID and password.

    1 Enter account details

  3. The Customer checks the payment resume and proceeds with the payment by clicking on the Confirm button. For test purposes, please choose and click Paid status from the ones provided on the page.

    1 Payment confirmation

  4. The customer receives a message that the payment has been completed correctly.

    1 Payment confirmation

  5. Upon completion of the payment flow the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

PostFinance e-finance Test Data

For PostFinance e-finance payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PostFinance e-finance Payment Flow

  1. The customer enters his e-finance number or usernames and password. For customers with several users (e.g. partner account): they need to enter their user ID as well. He confirms by using Next button.

    1 Login details

  2. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

PostFinance Card Test Data

For PostFinance Card payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

PostFinance Card Payment Flow

  1. The customer enters his ID number and continues the payment.

    1 ID Number

  2. The customer enters his Card Number. He finalizes the payment by using the Pay button.

    1 Card number

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Smart2Pay Android SDK Instructions for Credit Cards (Java)

The interaction flow is described next:

  1. Upon order initiation form the customer
  2. Your server asks our server for a temporary API Key at entry point api/authorization/apikey:

    Request:

    POST https://securetest.smart2pay.com/v1/authorization/apikey
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
  3. Our server responds with a temporary API Key:

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "ApiKey": {
        "Value": "MzAwMDc6M2FkODVhYzctNjhlNS00MTA2LTliNjctNTg3MmM1ZmI2ZDNiLTYzMzA=",
        "Created": "20181206141407",
        "LifeTime": 30,
        "AccessCounterLimit": 10,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }
  4. The temporary API Key must be passed to the app.

  5. From the app you collect the credit cards details from which you build a CardAuthenticationRequest object, together with the temporary API key obtained in the previous step. Set callback functions to handle Success and Failure cases.

    CardAuthenticationRequest cardAuthenticationRequest = new CardAuthenticationRequest("Basic " + apiKey, true);
    
    HashMap card = new HashMap();
    card.put("HolderName", ((EditText)findViewById(R.id.e_cardholder_name)).getText().toString());
    card.put("Number", ((EditText)findViewById(R.id.e_cc_number)).getText().toString());
    card.put("ExpirationMonth", ((EditText)findViewById(R.id.e_exp_month)).getText().toString());
    card.put("ExpirationYear", ((EditText)findViewById(R.id.e_exp_year)).getText().toString());
    card.put("SecurityCode", ((EditText)findViewById(R.id.e_cvv)).getText().toString());
    
    cardAuthenticationRequest.setRequestBody(CCAuthenticateRequestBodyBuilder.getBody(card));
    cardAuthenticationRequest.setCallback((new CardAuthenticationRequest.Callback() {
        public void onSuccess(@NonNull final String creditCardToken) {
            // Authorization was successful!
            // Send it to your server and initiate a transactions via REST API: https://docs.smart2pay.com/category/direct-card-processing/one-click-payment/
            Log.d("TokenForCreditCard", creditCardToken);
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Credit Card Token:" + creditCardToken);
                }
            });
        }
    
        public void onFailure() {
            Log.w(TAG,"Card Authentication request failed.");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Card Authentication request failed.");
                }
            });
        }
    }));
    cardAuthenticationRequest.enqueue();
    
  6. Our SDK calls our server with these details.
  7. The server responds with a token to our SDK.
  8. Our SDK passed the token back to your APP via the callback function setup in step 5.
  9. The order can now be submitted from the app to your server together with the token
  10. A credit card transaction using token is now initiated from your server. For more details go to: Recurring Card Payments section. You can store the token on your server for subsequent purchases.
  11. Our server responds to your server with the Authorization result. Upon a successful result you can release the goods or services.
  12. You pass the payment result to the app.

SDK is now fully functional in your app!

Smart2Pay iOS SDK Instructions (Swift)

Now that you have imported the Smart2Pay.SDK package into your app, you need to follow the below steps in order to set up the Mobile SDK for iOS in Swift language.

  1. To get back to the app after doing a payment we need to set an URL Scheme.

    Select the Project icon again in your file hierarchy – make sure you are in the Info tab – URL Types.

    Fold it open and click the + button. You only need to set URL Schemes field. For example, you can use your bundle identifier. This ensures that there’s no other app that uses this URL Scheme.

    We’re all set to make a payment now!

  2. Create a payment from the data you’ve attained from the API.

    
    ```
    Let payment = Payment(id: id)
    payment.amount = 100 // This is in cents
    payment.currency = "CNY" // Use the three letter abbreviation
    payment.type = .ALIPAY // or .WECHAT 
    payment.delegate = this // The current view controller with PaymentManagerDelegate implementation
    let paymentManager = PaymentManager("urlscheme from step 4")
    paymentManager.pay(payment)
    ```
    
  3. Make sure the view controller uses the delegate implementation:

    PaymentManager.PaymentManagerDelegate

    For example, your view controller could look like this:

    
    `
    class ViewController: UIViewController, PaymentManagerDelegate {
    `
    

    To get the callbacks from the Payment Manager you need to add these two functions:

    
    ```
    func onPaymentSuccess(_ payment: Payment, _ body: [String: Any]) {
    }
        
    func onPaymentFailure(_ payment: Payment) {
    }
    ```
    

    The information needed is inside the payment. This is the structure of a Payment:

    
    ```
    class Payment {
       enum PaymentProvider: Int {
            case NONE = 0
            case ALIPAY = 24
            case WECHAT = 1066
        }
        var id: Int = 0
        var type = PaymentProvider.NONE
        var amount: Int = 0
        var currency: String = ""
        var instructions: String = "" 
        var delegate: PaymentManagerDelegate?
    }
    ```
    

SDK is now fully functional in your app!

Smart2Pay iOS SDK Installation

You need to follow the below steps to build an in-app payment flow fully functional using Smart2Pay SDK in your iOS app using Swift.

  1. Download the Smart2Pay.framework.
  2. Import the framework into your project by either dragging it into the project or go to File | Add files to “project name”.
  3. Add the framework to the Embedded Binaries. Select the Project icon in your file hierarchy – make sure you are in the General tabEmbedded Binaries.

    There are three scenarios possible do the one that applies to you:

    • If you don’t see it in “Embedded Binaries” and don’t see it in the “Linked Frameworks and Libraries”, just click the + on “Embedded Binaries” and select the Smart2Pay.framework.
    • If you see it in “Linked Frameworks and Libraries” but not in “Embedded Binaries”, you should first remove it from “Linked Frameworks and Libraries” and click the + on “Embedded Binaries” and select the Smart2Pay.framework. This will automatically add it to both.
    • If you see it in both “Embedded Binaries” and “Linked Frameworks and Libraries”, you don’t need to do anything.

Now that the SDK is in the app we can actually use it in the code. Continue with setting up the SDK: Smart2Pay iOS SDK Instructions (Swift).

Mobile SDK – Cards

Besides Alipay and WeChat, our Mobile SDK can be used for in-app purchases using Credit Cards. The advantage of using our SDK is that the credit card details never reach your server, simplifying to a minimum the PCI requirements you must meet.

The interaction flow is described next:

  1. Upon order initiation form the customer
  2. Your server asks our server for a temporary API Key at entry point api/authorization/apikey:

    Request Model:

    POST https://securetest.smart2pay.com/v1/authorization/apikey
    Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=
  3. Our server responds with a temporary API Key:

    Response:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    
    {
      "ApiKey": {
        "Value": "MzAwMDc6M2FkODVhYzctNjhlNS00MTA2LTliNjctNTg3MmM1ZmI2ZDNiLTYzMzA=",
        "Created": "20181206141407",
        "LifeTime": 30,
        "AccessCounterLimit": 10,
        "Status": {
          "ID": 2,
          "Info": "Success",
          "Reasons": []
        }
      }
    }
  4. The temporary API Key must be passed to the app.

  5. From the app you collect the credit cards details from which you build a CardAuthenticationRequest object, together with the temporary API key obtained in the previous step. Set callback functions to handle Success and Failure cases.

    CardAuthenticationRequest cardAuthenticationRequest = new CardAuthenticationRequest("Basic " + apiKey, true);
    
    HashMap card = new HashMap();
    card.put("HolderName", ((EditText)findViewById(R.id.e_cardholder_name)).getText().toString());
    card.put("Number", ((EditText)findViewById(R.id.e_cc_number)).getText().toString());
    card.put("ExpirationMonth", ((EditText)findViewById(R.id.e_exp_month)).getText().toString());
    card.put("ExpirationYear", ((EditText)findViewById(R.id.e_exp_year)).getText().toString());
    card.put("SecurityCode", ((EditText)findViewById(R.id.e_cvv)).getText().toString());
    
    cardAuthenticationRequest.setRequestBody(CCAuthenticateRequestBodyBuilder.getBody(card));
    cardAuthenticationRequest.setCallback((new CardAuthenticationRequest.Callback() {
        public void onSuccess(@NonNull final String creditCardToken) {
            // Authorization was successful!
            // Send it to your server and initiate a transactions via REST API: https://docs.smart2pay.com/category/direct-card-processing/one-click-payment/
            Log.d("TokenForCreditCard", creditCardToken);
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Credit Card Token:" + creditCardToken);
                }
            });
        }
    
        public void onFailure() {
            Log.w(TAG,"Card Authentication request failed.");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    displayDebugInfo("Card Authentication request failed.");
                }
            });
        }
    }));
    cardAuthenticationRequest.enqueue();
    
  6. Our SDK calls our server with these details.
  7. The server responds with a token to our SDK.
  8. Our SDK passed the token back to your APP via the callback function setup in step 5.
  9. The order can now be submitted from the app to your server together with the token
  10. A credit card transaction using token is now initiated from your server. For more details go to: Recurring Card Payments section. You can store the token on your server for subsequent purchases.
  11. Our server responds to your server with the Authorization result. Upon a successful result you can release the goods or services.
  12. You pass the payment result to the app.

Roles Administration

The first user created for a merchant (the one created from the registration form) has a default role assigned. This role (Administrator) has all the access rights existent in the GlobalPay system.

69

Please note that access to this Roles Administration section is only available in production environment!

Click on Add a New Role button and you can create a new role. In the new form that opens, in the General section, you need to provide a role name and a description to the role. 69 In the Access Rights section you can assign access rights for the new role. When finished, click Save and your role will be created. The role you have just created is visible in the grid. You can create as many roles as you like. 70 If you want to remove or add new access rights to a role, or simply modify the name or the description you can click on the Edit button from the grid. And, of course, you can delete the roles you don’t need anymore using the Delete button from the grid.

Users Administration

When entering this section you will see in the grid your user and all the users you have created. These are all the users associated with your Merchant ID.

72

Please note that access to this Users Administration section is only available in production environment!

Click on Add a New User button and you can create a new user. In the new form that opens, in the General section, you need to provide a User Name and a User Email.

In the Roles section you can assign specific roles for the new user. You can assign to the new user one or more of the roles you have previously created.

In the Sites section you can assign specific websites to the new user. When finished, click Save and your new user will be created. Click Save and the new user will be saved and he will receive an email with the password. The User you have just created is visible in the grid. You can create as many users as you like.

Please note that a new user can also be created via API by submitting a POST HTTP request.

If you want to change user name or user email, remove or add roles or update the websites assign to an already created user, you need to click on the Edit button in the grid.

And, of course, you can delete the user accounts that do not serve you anymore using the Delete button from the grid.

74

In the Edit section you can also generate a new password for that specific user. When clicking Generate new password an email will be sent to that user with the new password.

Please be aware that if you assign a user a certain role (that contains specific access rights), that user will only have access to that restricted area defined by that role (and implicitly by the access rights).

Example:

You provide User1 with Role1 that includes NotificationURL-Update access right and Signature-Update access right. This means that User1 will only see two tabs when entering the dashboard: Account and Configuration. And he will have the right to generate a new signature and modify the Notification URL.

An update access right implicitly contains the view access right.

Example:

If the user has only one role that only contains the access right Signature-Update, that user will be able to see the Signature section and update the signature.

If the user has only one role that contains only Signature-view, that user will be able to access the Signature section, but won’t be able to update the signature.

Payment Methods

Here you will find a complete list of all the payment methods, you can easily verify the list of payment methods assigned to your merchant account or to request and activate new payment methods of your choice.

When you access the Payment Methods tab you will see a complete list of all the payment methods available for your merchant account. You have the possibility to search for specific payment methods using different search filters and to see the description for each payment method.

You can search for a specific payment method using the search filters available: payment method’s status, name, description, guaranteed status and countries available.

A very important step during the configuration process is setting up your payment methods. In this section you will be able to configure the preferred way to receive your payments and setup your desired payment methods. The payment methods are selected for an account when the account is created, but they can also be changed at any time needed.

There are a few possible actions available, in order for you to have a better management over your merchant account, that are explained below:

  • Request a new payment method:

    Using the first search filter from the top of the page, choose Can Request option from the dropdown list. A list of all the available payment methods that you can request for your account will appear.

    Once you find the desired payment method, click the “+” Request sign in front of it to add it to your account,

    A confirmation message will be displayed.

    After you have requested the payment method, you need to wait for Smart2pay approval of the payment method. Also, you can check the list of all your requested payment methods by using the first search filter from the top of the page. Choose Approval in Progress option from the dropdown list and a list of all your requested payment methods for your account will appear.

  • Activate a payment method:

    Using the first search filter from the top of the page, choose Can Activate option from the dropdown list. A list of all the payment methods assigned to your account that you can activate will appear.

    Once you find the desired payment method, click the Activate option in front of it to activate it.

    A confirmation message will be displayed.

    You need to wait for Smart2pay approval for the activation of the payment method. Also, you can check the list of all your payment methods that are waiting activation by using the first search filter from the top of the page. Choose Activation in Progress option from the dropdown list and a list of all your payment methods waiting activation will appear.

  • Deactivate a payment method:

    Using the first search filter from the top of the page, choose My Methods option from the dropdown list. A list of all the payment methods activated for your account will appear.

    If you want to deactivate a specific payment method, click the Deactivate option in front of it.

    A confirmation message will be displayed.

  • Ask for availability of a payment method:

    For some payment methods you need to ask our support team for more details regarding its availability. You can check the list of all the payment methods that need further guidance from our support team by using the first search filter from the top of the page. Choose Ask Availability option from the dropdown list and a list of all the payment methods that need further guidance from our support team will appear.

  • Unavailable payment methods:

    Some payment methods may be currently unavailable due to different external factors. You can check the list of all the unavailable payment methods by using the first search filter from the top of the page. Choose Unavailable option from the dropdown list and a list of all the unavailable payment methods will appear.

  • Rejected payment methods:

    If the request of a payment method will have a negative outcome we will let you know. You can check the list of all the rejected payment methods by using the first search filter from the top of the page. Choose Rejected option from the dropdown list and a list of all the rejected payment methods will appear.

iDEAL Implementation guide

iDEAL, one of the most used online banking method in the Netherlamds, allows the customer to buy securely on the Internet, directly from his bank account opened at one of the major Dutch banks: ABN AMRO, SNS Bank, RegioBank, Rabobank, Knab, Moneyou, ASN Bank, Triodos Bank, ING, Rabobank, Van Lanschot Bankiers,Knab, Bunq, Moneyou and Handelsbanken.

iDEAL was developed by the Dutch banking community in order to facilitate easier payment for online products and services. iDEAL enables direct and secure real-time online payments between bank accounts of Consumers and iDEAL Merchants. The main characteristics of iDEAL are:

  • Real-time payment through accepted and trusted Internet banking that is already familiar to Consumers;
  • Real-time payment authorisation for the Consumer and real-time confirmation to the Merchant by the Acquiring bank, followed by the irrevocable transfer of funds to the Merchant;
  • Suitability for online delivery (e.g. downloads, mobile top-ups), offline delivery (e.g. goods) and time-critical payments (e.g. airline tickets);
  • Offers the flexibility to make payments for many different purposes (e.g. charitable donations, telephone/e-mail orders).

Please ask support@smart2pay.com for the latest iDEAL Merchant Implementation Guide (MIG) and the necessary operation manuals.

iDEAL Four Party Model

When talking about iDeal transaction, one must know that there are at least four parties involved:

  • The Consumer: buys a product or service online from a Merchant that offers the iDEAL payment method
  • The Merchant: sells products or services online to Consumers
  • The Issuer (the Consumers’ bank): the Consumer executes iDEAL payments in his Internet banking environment – through his Issuer
  • The Acquirer (the Merchant’s bank): the Merchant accepts iDEAL payments – through his Acquirer

    Additional parties can be involved in an iDEAL transaction:

  • The Merchant can, for example, use a Payment Service Provider (PSP) to establish the connection with its Acquiring bank. When this PSP receives/collects the payments before they are paid to the Merchant, this is called a “Collecting PSP” (CPSP). In this case the Collecting PSP acts as the Merchant for the purpose of the iDEAL payments and holds the iDEAL contract with the Acquiring bank on behalf of one or multiple other Merchants.
Issuer Selection List Presentation

To ensure that the Consumer experience of an iDEAL transaction is consistent and recognizable through all Merchant websites; all Merchants have to comply with certain presentation standards:

  • All Issuers in the DirectoryResponse (to be collected at least monthly) have to be shown in a list (e.g. dropdown list or list of radio buttons) in alphabetic order and exactly as presented in the DirectoryResponse message.
  • The list should be accompanied by the instruction phrase “Kies uw bank” (UK: “Choose your bank”). In case of an HTML SELECT, the first element in the list states this instruction phrase and is selected by default (to prevent accidental Issuer selection).
  • It is not allowed to exclude or grey out any active Issuers from the Issuer list. In case of a new Issuer, the Issuer list should be updated wihtin one month (preferably earlier).
  • It is recommended to configure the HTML “value” field of the items in the list box to be the issuerID (BIC) of the corresponding Issuer, because this value is used in subsequent messages (TransactionRequest).
  • The Merchant may preselect an Issuer only to allow for an improved user experience (e.g. if the Consumer has previously initiated an iDEAL payment with a specific Issuer). The Consumer must however always be offered the possibility to alter the preselected Issuer.

An example of a correct presentation of the Issuer selection list is shown in the figure:

iDEAL banners and logo’s

Merchants that want to use a banner on their website to promote iDEAL can download the most recent banners at http://www.ideal.nl/en/payee/logos-banners/. These banners need to be installed only once, since the URL will always refer to the latest version of the banner containing the right logos of the participating Issuing banks.

The iDEAL logo must be used by anyone who offers iDEAL as a payment method, informing customers from the beginning that they can pay with iDEAL.

The iDEAL logo may only be used in the provided form and colour. The use of other colours is not permitted.

For more information and instructions for using the iDEAL logo, checkout the manual iDEAL logo.

POLi Test Data (Australia)

In order for you to test POLi payment method successfully, please use the below test data.

POLi Test Data
Data Value
User DemoShopper
Password DemoShopper

POLi Payment Flow (Australia)

  1. The Customer selects his Bank from the list and proceeds with the payment.

    1 Select bank

  2. The Customer enters the login details. He must fill the form with his Username and password and click the Login button.

    1 Login details

  3. The Customer needs to select the bank account he wants to transfer money from and click the Continue button.

    1 Select bank account

  4. The customer is redirected to the provider’s confirmation page where he sees the payment summary and details. He completes the transaction by clicking on the Confirm button.

    1 Transaction confirmation

  5. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Alipay Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for Alipay method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

For Alipay payments only the following Articles parameters are mandatory to be sent in the request, the rest of them are optional:

  • Name – Article’s name;
  • Quantity – The number of products.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request: 

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h31",
    "Amount": "100",
    "Currency": "CNY",      
    "MethodID": 24,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "BillingAddress": {
      "Country": "CN"
      },        
    "Articles": [
      { 
      "Name": "TEST",
      "Quantity": 1
      }
    ]
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4201852,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181120122556",
        "MerchantTransactionID": "s2ptest_h31",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "CNY",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "MethodID": 24,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": "20181120122556",
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": [
            {
                "MerchantArticleID": null,
                "Name": "TEST",
                "Quantity": 1,
                "Price": null,
                "VAT": null,
                "Discount": null,
                "Type": null,
                "TaxType": null,
                "DiscountValue": null
            }
        ],
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h32",
    "Amount": "100",
    "Currency": "CN",      
    "MethodID": 24,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "BillingAddress": {
      "Country": "CN"
      },
        
    "Articles": [
      { 
      "Name": "TEST",
      "Quantity": 1
      }
    ]
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": null,
        "SkinID": null,
        "ClientIP": null,
        "Created": null,
        "MerchantTransactionID": "s2ptest_h32",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "CN",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": null,
        "MethodID": 24,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": null,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": null,
            "Info": null,
            "Reasons": [
                {
                    "Code": "2",
                    "Info": "Validation failed - Currency (RegEx: ^[A-Z]{3}$)"
                }
            ]
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

API Idempotence

Idemptotence is the property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application.

When talking about API calls, idempotency means that if you attempt an operation twice or more, only the first attempt will be processed. Idempotence prevents the processing of duplicate requests by using unique keys.

If a network connection error or a timeout error appears when creating a card payment, you can do a retry. But still, in this case, there is the possibility that the card payment has already been created, leading you only to generate a duplicate payment when you do the retry.

In order to avoid this undesired scenario, we have implemented a new piece of functionality using Unique Keys, which make it safe to retry non-idempotent API requests. These Unique Keys or Idempotence keys ensure that no matter the number of retries for a specific call only one response action is executed, and the payment is not duplicated.

Our API supports idempotence for safely retrying requests and guarantees that the operation is performed only once. Therefore, if you create a card payment that fails due to a network connection error, you can retry the request with the same idempotence key to guarantee that only a single card payment is created.

Idempotence keys are unique value generated keys, for example, UUIDs, that you submit as a request header and guarantee that only one resource will be created regardless of how many times a request is sent to the server.

Idempotence keys can be generated using your own preferred method or any appropriately random string. Still, we recommend to generate your own Unique Keys (Idempotence keys) using V4 UUIDs.

For card payments we’ll always send back the same response for requests made with the same key, and keys can’t be reused with different request parameters. The keys are stored for a period of 24 hours.

You can also visit our Smart2Pay SDK .NET section for more information on how you can generate and plug in your Unique Key Generator.

Alipay Test Data

For Alipay payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

Alipay Payment Flow

  1. The Customer selects his preferred currency from the list and continues the payment.

    1 Select currency

  2. Once the customer arrives at the provider’s page he has two choices: to continue with the payment using the mobile version or using the desktop version.

    1 Payment version

  3. The customer logs in to his Alipay account by entering his email address and password.

    1 Account login

  4. The customer confirms the payment by entering the payment password.

    1 Payment password

  5. The payment is processing.

    1 Payment processing

  6. In a few seconds the customer will be redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

WeChat Test Data

For WeChat payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

WeChat Payment Flow

  1. The customer selects his preferred currency from the list and enters his email address.

    1 Enter email

  2. You can skip this step by sending in the initial POST the following parameters: SkipHPP=1 and CustomerEmail.

  3. The Customer is redirected to WeChat payment page.

    1 WeChat payment page

  4. The Customer opens WeChat application and scans the QR code.

    1 QR code scanning

  5. The payment details are displayed and the customer confirms by using the payment password.

    1 Payment confirmation

  6. The payment is confirmed.

    1 Payment successful

  7. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is Processing

Multibanco SIBS Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for Multibanco SIBS method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

In order to display the payment details to your customers on your own page, you can send in the request the CustomerName and Country parameters. Use the information received in Response in the ReferenceDetails object.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request: 

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
   "Payment": {
      "MerchantTransactionID": "s2ptest_h40",
      "Amount": "400",
      "Currency": "EUR",
      "ReturnURL": "http://demo.smart2pay.com/redirect.php",
      "Description": "SIBSTestDetails",
      "MethodID": 20,
      "BillingAddress": {
         "Country": "PT"
      },
      "Customer": {
         "FirstName": "John",
         "LastName": "Doe"
      }
   }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4178449,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181107100206",
        "MerchantTransactionID": "s2ptest_h40",
        "OriginatorTransactionID": null,
        "Amount": "400",
        "Currency": "EUR",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "SIBSTestDetails",
        "MethodID": 20,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": {
            "ID": 142823,
            "MerchantCustomerID": null,
            "Email": null,
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 705,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "PT"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": {
            "BankCode": null,
            "BankName": null,
            "EntityID": null,
            "EntityNumber": "11302",
            "ReferenceID": null,
            "ReferenceNumber": "022 518 828",
            "SwiftBIC": null,
            "AccountCurrency": null,
            "AccountNumber": null,
            "AccountHolder": null,
            "IBAN": null,
            "AmountToPay": "4 EUR",
            "QRCodeURL": null,
            "Instructions": null
        },
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 1,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=DAB863DD12A9DB642BF15252CB89CAC2.4178449"
    }
}

Bank Transfer Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for Bank Transfer method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

In order to display the bank transfer details to your customers on your own page, you can send in the request the CustomerName and Country parameters. Use the information received in Response in the ReferenceDetails object.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request: 

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment":{
    "MerchantTransactionID": "s2ptest_h35",
    "Amount": 400,
    "Currency": "PLN",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "BankTransferTestdetails",
    "MethodID": "1",
    "BillingAddress": {
      "Country": "DE"
    },
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4178425,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181107093433",
        "MerchantTransactionID": "s2ptest_h35",
        "OriginatorTransactionID": null,
        "Amount": "400",
        "Currency": "PLN",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "BankTransferTestdetails",
        "MethodID": 1,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": {
            "ID": 142823,
            "MerchantCustomerID": null,
            "Email": null,
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 420,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "DE"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": {
            "BankCode": null,
            "BankName": "ING Bank",
            "EntityID": null,
            "EntityNumber": null,
            "ReferenceID": null,
            "ReferenceNumber": "HPP4178425",
            "SwiftBIC": "INGBDEFF",
            "AccountCurrency": "EUR",
            "AccountNumber": "0010126423",
            "AccountHolder": "Stichting Smart2Pay Escrow Services",
            "IBAN": "DE72 5002 1000 0010 1264 23",
            "AmountToPay": "0.93 EUR",
            "QRCodeURL": null,
            "Instructions": null
        },
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 1,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=F152AF870FFF05B98A83F7B8C35A81D9.4178425"
    }
}

There is another possibility to initiate a Bank Transfer transaction where you can send your own Reference Number in the request. Checkout the below example with the ReferenceNumber parameter sent in the request together with Customer parameters:

Request:

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h39",
    "Amount": 400,
    "Currency": "PLN",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "BankTransferTestdetails",
    "MethodID": "1",
    "BillingAddress": {
      "Country": "DE"
    },
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe"
    },
    "Details": {
      "ReferenceNumber": "your_reference_number"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4178441,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181107095318",
        "MerchantTransactionID": "s2ptest_h39",
        "OriginatorTransactionID": null,
        "Amount": "400",
        "Currency": "PLN",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "BankTransferTestdetails",
        "MethodID": 1,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": {
            "ID": 142823,
            "MerchantCustomerID": null,
            "Email": null,
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 420,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "DE"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": {
            "AccountNumber": null,
            "AccountHolder": null,
            "IBAN": null,
            "BIC": null,
            "PrepaidCard": null,
            "PrepaidCardPIN": null,
            "SerialNumbers": null,
            "Wallet": null,
            "ReferenceNumber": null,
            "PayerCountry": null,
            "PayerEmail": null,
            "PayerPhone": null,
            "BankCode": null,
            "BankName": null,
            "BankSortCode": null,
            "SocialSecurityNumber": null,
            "BillingCycleStart": null,
            "BillingCycleEnd": null,
            "UnsubscribeInstructions": null,
            "CustomerLoginID": null,
            "PaidAmount": null,
            "PaidCurrency": null,
            "ProviderExchangeRate": 0,
            "PayerBankAccountID": null
        },
        "ReferenceDetails": {
            "BankCode": null,
            "BankName": "ING Bank",
            "EntityID": null,
            "EntityNumber": null,
            "ReferenceID": null,
            "ReferenceNumber": "your_reference_number",
            "SwiftBIC": "INGBDEFF",
            "AccountCurrency": "EUR",
            "AccountNumber": "0010126423",
            "AccountHolder": "Stichting Smart2Pay Escrow Services",
            "IBAN": "DE72 5002 1000 0010 1264 23",
            "AmountToPay": "0.93 EUR",
            "QRCodeURL": null,
            "Instructions": null
        },
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": 1,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=DDC981EDC0426B8C22F57F88FD8B0FF4.4178441"
    }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_h36",
    "Amount": 400,
    "Currency": "PLN",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "BankTransferTestdetails",
    "MethodID": "1",
    "BillingAddress": {
      "Country": "Germany"
    },
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe"
    }
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4178427,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181107094050",
        "MerchantTransactionID": "s2ptest_h36",
        "OriginatorTransactionID": null,
        "Amount": "400",
        "Currency": "PLN",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "BankTransferTestdetails",
        "MethodID": 1,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": "20181107094050",
        "Customer": null,
        "BillingAddress": null,
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 4,
            "Info": "Failed",
            "Reasons": [
                {
                    "Code": "147",
                    "Info": "Address details are invalid (BillingAddress)Country - RegEx: ^[a-zA-Z]{2}$;"
                }
            ]
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

SEPA Direct Debit Recurring Payment Notification

You need to respond with HTTP code 204 (No Content)!

Payment notification for status Success (2):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4167022,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181101145458",
    "MerchantTransactionID": "s2ptest_h13",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "ReturnURL": "",
    "Description": null,
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13199,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": null
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

The message contains a Payment object with an updated Status, which can have the following meanings:

RECURRING PAYMENT STATUS
ID Info Description
2 Success The transaction is successfully settled by the bank.
4 Failed The transaction has failed.
16 Reversed The customer did not recognize the payment and requested the funds back from his bank.
  • In case of a Failed or Reversed status, you will be given in the notification message the reasons why the payment got to that status. Additional information will be sent in the Reasons Code and Reasons Info fields. For a complete list of possible return codes please see our section GlobalPay Return Codes.

SEPA Direct Debit Return Codes
Return Code Description
221 R-Transaction : AC01 – Account Identifier incorrect (i.e. invalid IBAN of the Debtor).
222 R-Transaction : AC04 – Account closed.
223 R-Transaction : AC06 – Account blocked.
224 R-Transaction : AC13 – Debtor account is a consumer account.
225 R-Transaction : AC13 – Debtor account is a consumer account.
226 R-Transaction : AG02 – Operation code/transaction code/sequence type incorrect, invalid file format.
227 R-Transaction : AM04 – Insufficient funds.
228 R-Transaction : AM05 – Duplicate collection.
229 R-Transaction : BE05 – Identifier of the Creditor Incorrect.
230 R-Transaction : CNOR – Creditor Bank is not registered under this BIC in the CSM.
231 R-Transaction : DNOR – Debtor Bank is not registered under this BIC in the CSM.
232 R-Transaction : FF01 – File Format incomplete or invalid.
233 R-Transaction : MD01 – No mandate.
234 R-Transaction : MD02 – Mandate data missing or incorrect.
235 R-Transaction : MD06 – Disputed authorized transaction.
236 R-Transaction : MD07 – Debtor Deceased.
237 R-Transaction : MS02 – Refusal by the Debtor.
238 R-Transaction : MS03 – Reason not specified.
239 R-Transaction : RC01 – Bank Identifier (BIC) Incorrect.
240 R-Transaction : RR01 – Regulatory Reason.
241 R-Transaction : RR02 – Regulatory Reason.
242 R-Transaction : RR03 – Regulatory Reason.
243 R-Transaction : RR04 – Regulatory Reason.
244 R-Transaction : SL01 – Specific Service offered by the Debtor Bank.

Payment notification for status Failed with reason code and description.

Payment notification for status Failed (4):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4157363,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181029134811",
    "MerchantTransactionID": "testCORE00001",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": "test Smart2Pay",
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30151,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": {
      "ID": 1720,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13165,
    "Status": {
      "ID": 4,	
      "Info": "Failed",
      "Reasons": [
        {	
          "Code": "227",
          "Info": "R-Transaction : AM04 - Insufficient funds"
        }	
      ]	
    },	
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

Payment notification for status Reversed with reason code and description.

Payment notification for status Reversed (16):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "ID": 4157363,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181029134811",
    "MerchantTransactionID": "testCORE00001",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "CapturedAmount": null,
    "ReturnURL": "",
    "Description": "test Smart2Pay",
    "MethodID": 84,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30151,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": {
      "ID": 1720,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": 13165,
    "Status": {
      "ID": 16,	
      "Info": "Reversed",
      "Reasons": [
        {	
          "Code": "235",
          "Info": "R-Transaction : MD06 - Disputed authorized transaction."
        }	
      ]	
    },	
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Response:

204 No Content

SEPA Direct Debit Preapproval Notification

Upon successful approval, we will notify you about the new status of the preapproval to the URL you setup in the Merchant Dashboard.

You need to respond with HTTP Status 204 (No Content)!

Preapproval notification for status Open (2):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 13199,
    "Created": "20181101142508",
    "MethodID": 84,
    "SiteID": 30201,
    "MerchantPreapprovalID": "s2ptest_h11",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "SEPA DD preapproval request",
    "Customer": {
      "ID": 135127,
      "MerchantCustomerID": null,
      "Email": "youremail@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": null,
      "SocialSecurityNumber2": null,
      "Phone": "+31651111111",
      "Company": null,
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 5103,
      "City": "Laren",
      "ZipCode": "1251",
      "State": null,
      "Street": "Brink",
      "StreetNumber": "27c",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "NL"
    },
    "Status": {
      "ID": 2,
      "Info": null,
      "Reasons": null
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": "SLMP004606504"
  }
}

Response:

204 No Content

The message contains a Preapproval object with an updated Status, which can have the following meanings:

PREAPPROVAL STATUS
ID Info Description
1 Pending The customer needs to confirm the preapproval
2 Open The customer confirmed and you can use the preapproval to initiate recurring payments
4 ClosedByCustomer The preapproval is closed and can no longer be used to initiate recurring payments

If the mandate is cancelled by the customer or there is an error in the creation process than a notification with the specific reason is sent.

Preapproval notification for status ClosedByCustomer (4):

Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "ID": 729222,
    "Created": "20181025083420",
    "MethodID": 84,
    "SiteID": 30025,
    "MerchantPreapprovalID": "preapptestingS4526352",
    "RecurringPeriod": 0,
    "PreapprovedMaximumAmount": null,
    "Currency": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "sample description",
    "Customer": {
      "ID": 341703,
      "MerchantCustomerID": null,
      "Email": "youremail@gmail.com",
      "FirstName": "John",
      "LastName": "Doe",
      "Gender": null,
      "SocialSecurityNumber": "",
      "SocialSecurityNumber2": null,
      "Phone": "+40765260000",
      "Company": "Smart2Pay",
      "DateOfBirth": null
    },
    "BillingAddress": {
      "ID": 8438,
      "City": "Iași",
      "ZipCode": "23900000",
      "State": null,
      "Street": "Sf. Lazar",
      "StreetNumber": "1",
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "RO"
    },
    "Status": {
      "ID": 4,
      "Info": null,
      "Reasons": [
        {
          "Code": "246",
          "Info": "Preapproval cancelled by consumer"
        }
      ]
    },
    "RedirectURL": null,
    "MethodOptionID": 0,
    "PreapprovedFrequency": null,
    "MandateReference": null
  }
}

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

SEPA Direct Debit Preapproval Request

General information to be known for SEPA Direct Debit:

  • The customer’s bank needs to be enrolled in the SEPA Direct Debit CORE scheme or this service needs to be activated on the customer’s bank account.
  • Ask customer to make sure they have the necessary funds in their account. Up to 80% of payments failures are caused by insufficient amount.
  • According to SEPA Direct Debit rules, the customers can Reverse/Cancel a Direct Debit (claim the money back) in 8 weeks, no questions asked and up to 13 months, if his bank agrees. If this happens, you will receive a Reversed notification with ReasonCode and Reason (R-Transaction) which you should properly handle on your side.
  • For B2B transactions please add the CompanyName parameter.
  • The currency for SEPA Direct Debit CORE is EUR, however the customers can use their account although this is not an EUR account as long as the bank is enrolled in SEPA Direct Debit CORE scheme. In this case, some exchange fees might be charged by their bank.

Checkout the below example of a preapproval request for SEPA Direct Debit (84), where MethodOptionID parameter is mandatory to be sent in the initial payment request.

Please note that if you have a Company, you also need to send the Company parameter in the request.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

Request: 

POST https://paytest.smart2pay.com/v1/preapprovals
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Preapproval": {
    "MerchantPreapprovalID": "s2ptest_h11",
    "Description": "SEPA DD preapproval request",
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "MethodID": 84,
    "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "youremail@gmail.com",
      "Phone": "+31651111111"
    },
    "BillingAddress": {
      "Street": "Brink",
      "StreetNumber": "27c",
      "ZipCode": "1251",
      "City": "Laren",
      "Country": "NL"
    },
    "MethodOptionID": 1
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Preapproval": {
        "ID": 13199,
        "Created": "20181101142508",
        "MethodID": 84,
        "SiteID": 30201,
        "MerchantPreapprovalID": "s2ptest_h11",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": null,
        "Currency": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "SEPA DD preapproval request",
        "Customer": {
            "ID": 135127,
            "MerchantCustomerID": null,
            "Email": "youremail@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "SocialSecurityNumber2": null,
            "Phone": "+31651111111",
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 5103,
            "City": "Laren",
            "ZipCode": "1251",
            "State": null,
            "Street": "Brink",
            "StreetNumber": "27c",
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "NL"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/SlimPay/Landing/PreapprovalLanding.aspx?ID=10084&Hash=CD71CA781BD1F59F52F8F0B2D20A807E",
        "MethodOptionID": 1,
        "PreapprovedFrequency": null,
        "MandateReference": null
    }
}

Redirect the customer to the RedirectURL where he will approve the automatic debit. Once the Customer approves the debit, he will receives via email the digital signed mandate.

SEPA Direct Debit Timeline

Checkout the below SEPA Direct Debit Timeline explained:

  • D-14: Pre-notification for recurrent Direct Debits;
  • D-2: The merchant initiates a SEPA DD – the payment has status Open. If the Direct debit request fails for technical reasons (e.g connection time out), the payment status moves to Failed with ReasonCode and Reason. This is not an incident (R-transaction), it is only a technical failure of the request;
  • D-1: The provider submits the SEPA DD into the network. If the SEPA DD is initiated early in the morning, then it will be submitted in the network in the same day D-1;
  • D: The D day is known as the Execution day for a SEPA Direct Debit;
  • D+2: the payment remains Open unless an incident (R-Transaction) is reported. If an incident – reject, refusal, return – is registered, a notification for status Failed with ReasonCode and Reason (including the R-Transaction code) will be sent to the merchant;
  • D+6: If no incident occurred until D+5, the transaction is settled and the SEPA DD updates to status Success. Now the merchant can provide the product/service to the customer;
  • D+6 -> D+8 weeks / D+13 months: If the customer does not recognize the Direct Debit, he can claim the money back in 8 weeks, no questions asked and up to 13 months, if the customer’s bank agrees. This situation is also considered an incident (R-Transaction). If this happens, you will receive a Reversed notification with ReasonCode and Reason (including the R-Transaction) which you should properly handle on your side.

All days should be considered banking days!

Pre-notification:

Debtor pre-notification: is a 14 days notification period (this can be reduced upon debtor agreement).

This pre-notification must include the following information: the payment due date, the payment amount, the Unique Mandate Reference and the merchant Creditor Identifier. There is no requirement regarding the method of communication, meaning that this can be done through agreement on General Terms and Conditions, it can be solely written on an invoice, it can be displayed in an online customer account.

For more information about the reasons of a wrong request response, please go to our section: GlobalPay Return Codes.

SEPA Direct Debit Recurring Payment

Based on the PreapprovalID received, Direct Debits can be initiated.

Checkout the below example of a recurring payment request for SEPA Direct Debit (84) that is based on the PreapprovalID. Please send in the payment request the Description parameter and Country parameter that should be the same with the ones sent in the Preapproval request.

Request:

POST https://paytest.smart2pay.com/v1/payments/recurrent
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
 "Payment": {
   "PreapprovalID":13199,
   "MerchantTransactionID": "s2ptest_h13",
   "Amount": 100,
   "Currency": "EUR",
   "MethodID": 84,
   "Description":"SEPA DD recurrent payment",
   "BillingAddress": {
     "Country": "NL"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4167022,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20181101145456",
        "MerchantTransactionID": "s2ptest_h13",
        "OriginatorTransactionID": null,
        "Amount": "100",
        "Currency": "EUR",
        "CapturedAmount": null,
        "ReturnURL": null,
        "Description": "SEPA DD recurrent payment",
        "MethodID": 84,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": null,
        "BillingAddress": {
            "ID": 309,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "NL"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": null,
        "ReferenceDetails": null,
        "CustomParameters": null,
        "PreapprovalID": 13199,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "MethodTransactionID": null,
        "TokenLifetime": null,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": null
    }
}

Smart2Pay Android SDK Instructions for Alipay and Wechat (Kotlin)

Now that you have imported the Smart2Pay.SDK package into your app, you need to follow the below steps in order to set up the Mobile SDK for Android in Kotlin language.

If you are using Java go to our section: Smart2Pay Mobile SDK Configuration using Java language.

First of all you need to start using and install the Kotlin plugin for Android development. For more information, please visit: Getting started with Android and Kotlin.

Configure Kotlin in your project by following the steps below:

  • Click Tools | Kotlin | Configure Kotlin in Project.
  • Select Android.
  • Check if all modules and the selected Kotlin version are correct.
  • Press OK and Kotlin is now part of your Java project.
  1. [APP] Create an order to your server

    //sample code, put your own logic of creating an order to your server
    val orderParameters = HashMap<String, Any>()
            orderParameters["amount"] = "10"
            orderParameters["currency"] = "CNY"
            orderParameters["methodID"] = paymentManager.getMethodId(payment.type).toString()
    
            val paymentsRequest = PaymentsRequest(RequestManager.instance)
            paymentsRequest.setRequestBody(orderParameters)
            paymentsRequest.callback =
                    object : PaymentsRequest.Callback {
                        override fun onSuccess(paymentId: Int, paymentsResponse: String) {
                            payment.id = paymentId
                            payment.instructions = paymentsResponse
                            paymentManager.pay(payment)
                        }
    
                        override fun onFailure() {
    
                        }
                    }
            paymentsRequest.enqueue()
    
  2. [SERVER] Once the order is created on your server, from the server create a Payment using our REST API and specifying isMobileApp: true.

    
    {
      "Payment": {
        "MerchantTransactionID": "{{tester}}-{{env}}-{{time}}-{{rand}}",
        "Amount": "100",
        "Currency": "CNY",
        "ReturnURL": "https://www.merchant.com/return",
        "MethodID" : "24",
        "Customer":{
          "Email": "john.doe@isp.com"
        },
        "Details":{
        "IsMobileApp": true
        }
    
      }
    }
    
  3. [SERVER] Our server responds with Instructions field which you need to pass to the app.

    {
      "Payment": {
        "ID": 4164863,
        "MethodID": 24,
        […]
        },
        "ReferenceDetails": {
    […]
          "Instructions": "_input_charset=\"utf-8\"&appenv=\"system=android^version=3.0.1.2\"&body=\"Alipay Payment\"&currency=\"USD\"&forex_biz=\"FP\"&notify_url=\"https://europaytest.smart2pay.com/Alipay/Landing/AlipayNotificationURL.aspx\"&out_trade_no=\"s2ptest200336\"&partner=\"2088201612260077\"&payment_type=\"1\"&rmb_fee=\"1\"&secondary_merchant_id=\"GP1045\"&secondary_merchant_industry=\"5946\"&secondary_merchant_name=\"demo iasi test\"&seller_id=\"2088201612260077\"&service=\"mobile.securitypay.pay\"&subject=\"Alipay Payment\"&supplier=\"demo iasi test\"&sign=\"vRQ1ouMvn0rJUCxSEi91RLJcS0NU7mojYfJpfT8gxtctF8jfJ4x6uN8t0ETdDdmGziqP7IsYHTSAHdFLHGO4hQdovyzJMna42nc9DcfMMlhTX7ZVCa7rUuieBWcW0ek8w3DxojrWnWT9lM3lUQZVLsY1CjXFGJ126x4TnjrA86w%3d\"&sign_type=\"RSA\""
          },
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": null
          },
          […]
      }
    }
    
  4. [APP] Pass the instructions from the response to the payment object together with the payment type and Activity.

    override fun onSuccess(paymentId: Int, paymentsResponse: String) {
                            payment.id = paymentId
                            payment.instructions = paymentsResponse
                            payment.activity = this@MainActivity
                            […]
                            }
    
  5. [APP] Call Smart2Pay Mobile SDK by calling pay() function from the paymentManager object.

    override fun onSuccess(paymentId: Int, paymentsResponse: String) {
                            [...]
                            paymentManager.pay(payment)
                            }
    

    The information needed inside the Payment object of our mobile SDK:

    class Payment {
        enum class PaymentProvider {
            NONE,
            ALIPAY,
            WECHAT
        }
        var id: Int = 0
        var type = PaymentProvider.NONE
        var instructions: String = "" 
        var activity: Activity
    }

    When pasting this into your code the imports should go automatically or you can add them manually:

    import com.smart2pay.sdk.PaymentManager
    import com.smart2pay.sdk.models.Payment
  6. [SDK] Our SDK triggers Alipay or WeChat application

  7. [User] The user completes the payment

  8. [SDK] Alipay or WeChat application passes the status to our mobile SDK

  9. [APP] Our SDK calls one of the two callbacks onPaymentSuccess or onPaymentFailure, depending on the payment result.

    Make sure the activity uses the Interface:

    PaymentManager.PaymentManagerEventListener

    For example your activity could look like this:

    class MainActivity : AppCompatActivity(), PaymentManager.PaymentManagerEventListener {

    Add these two functions to get the callbacks from the Payment Manager:

    override fun onPaymentFailure(payment: Payment) {
    }
    override fun onPaymentSuccess(payment: Payment) {
    }
  10. [APP] Inside onPaymentSuccess, before displaying the result to the user and providing the service you need to do a server verification by calling from the server our payment verification API. Call your server from the App to ask for the verification result. – (Only for Alipay payments)

  11. [SERVER] You need to pass the Smart2Pay payment ID and the message received from Smart2Pay mobile SDK. – (Only for Alipay payments)

    POST {{entryPoint}}/{{version}}/payments/{id}/verify
    
    {
       "message": "partner=\"2088101568358171\"&out_trade_no=\"0819145412-6177\"&subject=\"test\"&body=\"testtest\"&total_fee=\"0.01\"&notify_url=\"http://notify.msp.hk/notify.htm\"&service=\"mobile.securitypay.pay\"&payment_type=\"1\"&_input_charset=\"utf-8\"&it_b_pay=\"30m\"&success=\"true\"&sign_type=\"RSA\"&sign=\"hkFZr+zE9499nuqDNLZEF7W75RFFPsly876QuRSeN8WMaUgcdR00IKy5ZyBJ4eldhoJ/2zghqrD4E2G2mNjs3aE+HCLiBXrPDNdLKCZgSOIqmv46TfPTEqopYfhs+o5fZzXxt34fwdrzN4mX6S13cr3UwmEV4L3Ffir/02RBVtU="
    }
    
  12. [SERVER] Our API checks the transaction and replies back with the status of the verification. – (Only for Alipay payments)

    {
        "status": "Success"
    }
    
  13. [SERVER] If the “status” is Success you can deliver the goods or services. Pass this result to the App. – (Only for Alipay payments)

  14. [APP] Display the payment result to the user.

  15. [SERVER] As a backup for any client communication issues, Smart2Pay will also send to your server a backend notification as documented here: Payment Notification.

SDK is now fully functional in your app!

Smart2Pay Android SDK Instructions for Alipay and Wechat (Java)

Now that you have imported the Smart2Pay.SDK package into your app, you need to follow the below steps in order to set up the Mobile SDK for Android in Java language.

If you are using Kotlin go to our section: Smart2Pay Mobile SDK Configuration using Kotlin language.

  1. [APP] Create an order to your server

    //sample code, put your own logic of creating an order to your server
    order order = new Order()
    order.setAmount(1);
    order.setCurrency("CNY");
    order.setType(Payment.PaymentProvider.ALIPAY); //or Payment.PaymentProvider.WECHAT
    order.create();
    
  2. [SERVER] Once the order is created on your server, from the server create a Payment using our REST API and specifying isMobileApp: true.

    {
      "Payment": {
        "MerchantTransactionID": "{{tester}}-{{env}}-{{time}}-{{rand}}",
        "Amount": "100",
        "Currency": "CNY",
        "ReturnURL": "https://www.merchant.com/return",
        "MethodID" : "24",
        "Customer":{
          "Email": "john.doe@isp.com"
        },
        "Details":{
          "IsMobileApp": true
        }
      }
    }
    
  3. [SERVER] Our server responds with Instructions field which you need to pass to the app.

    {
      "Payment": {
        "ID": 4164863,
        "MethodID": 24,
        […]
        },
        "ReferenceDetails": {
    […]
          "Instructions": "_input_charset=\"utf-8\"&appenv=\"system=android^version=3.0.1.2\"&body=\"Alipay Payment\"&currency=\"USD\"&forex_biz=\"FP\"&notify_url=\"https://europaytest.smart2pay.com/Alipay/Landing/AlipayNotificationURL.aspx\"&out_trade_no=\"s2ptest200336\"&partner=\"2088201612260077\"&payment_type=\"1\"&rmb_fee=\"1\"&secondary_merchant_id=\"GP1045\"&secondary_merchant_industry=\"5946\"&secondary_merchant_name=\"demo iasi test\"&seller_id=\"2088201612260077\"&service=\"mobile.securitypay.pay\"&subject=\"Alipay Payment\"&supplier=\"demo iasi test\"&sign=\"vRQ1ouMvn0rJUCxSEi91RLJcS0NU7mojYfJpfT8gxtctF8jfJ4x6uN8t0ETdDdmGziqP7IsYHTSAHdFLHGO4hQdovyzJMna42nc9DcfMMlhTX7ZVCa7rUuieBWcW0ek8w3DxojrWnWT9lM3lUQZVLsY1CjXFGJ126x4TnjrA86w%3d\"&sign_type=\"RSA\""
        },
        "Status": {
          "ID": 1,
          "Info": "Open",
          "Reasons": null
          },
       […]
      }
    }
    
  4. [APP] Get the instructions from the server response.

    String instructions = order.getInstructions();
  5. [APP] Call Smart2Pay Mobile SDK by creating a Payment object, passing the Activity, payment type and instructions. Then trigger the payment using a PaymentManager object.

    Payment payment = new Payment();
        payment.setInstructions(instructions);
        payment.setType(Payment.PaymentProvider.ALIPAY);
        payment.setActivity(this);
    
        PaymentManager paymentManager = new PaymentManager();
        paymentManager.pay(payment);

    The information needed inside the Payment object of our mobile SDK:

    class Payment {
        enum PaymentProvider {
            NONE,
            ALIPAY,
            WECHAT
        };
        int ID;
        PaymentProvider type;
        String instructions;
        Activity activity;
    }

    When pasting this into your code the imports should go automatically or you can add them manually:

    import com.smart2pay.sdk.PaymentManager;
    import com.smart2pay.sdk.models.Payment;
  6. [SDK] Our SDK triggers Alipay or WeChat application

  7. [User] The user completes the payment

  8. [SDK] Alipay or WeChat application passes the status to our mobile SDK

  9. [APP] Our SDK calls one of the two callbacks onPaymentSuccess or onPaymentFailure, depending on the payment result.

    Make sure the activity uses the Interface:

    PaymentManager.PaymentManagerEventListener

    For example your activity could look like this:

    public class MainActivity extends AppCompatActivity implements PaymentManager.PaymentManagerEventListener {

    Add these two functions to get the callbacks from the Payment Manager:

    @Override
    public void onPaymentSuccess(Payment payment) {
        
    }
    @Override
    public void onPaymentFailure(Payment payment) {
        
    }
  10. [APP] Inside onPaymentSuccess, before displaying the result to the user and providing the service you need to do a server verification by calling from the server our payment verification API. Call your server from the App to ask for the verification result. – (Only for Alipay payments)

  11. [SERVER] You need to pass the Smart2Pay payment ID and the message received from Smart2Pay mobile SDK. – (Only for Alipay payments)

    POST {{entryPoint}}/{{version}}/payments/{id}/verify
    
    {
       "message": "partner=\"2088101568358171\"&out_trade_no=\"0819145412-6177\"&subject=\"test\"&body=\"testtest\"&total_fee=\"0.01\"&notify_url=\"http://notify.msp.hk/notify.htm\"&service=\"mobile.securitypay.pay\"&payment_type=\"1\"&_input_charset=\"utf-8\"&it_b_pay=\"30m\"&success=\"true\"&sign_type=\"RSA\"&sign=\"hkFZr+zE9499nuqDNLZEF7W75RFFPsly876QuRSeN8WMaUgcdR00IKy5ZyBJ4eldhoJ/2zghqrD4E2G2mNjs3aE+HCLiBXrPDNdLKCZgSOIqmv46TfPTEqopYfhs+o5fZzXxt34fwdrzN4mX6S13cr3UwmEV4L3Ffir/02RBVtU="
    }
  12. [SERVER] Our API checks the transaction and replies back with the status of the verification. – (Only for Alipay payments)

    {
        "status": "Success"
    }
    
  13. [SERVER] If the “status” is Success you can deliver the goods or services. Pass this result to the App. – (Only for Alipay payments)

  14. [APP] Display the payment result to the user.

  15. [SERVER] As a backup for any client communication issues, Smart2Pay will also send to your server a backend notification as documented here: Payment Notification.

SDK is now fully functional in your app!

Smart2Pay Android SDK Installation

You need to follow the below steps to build an in-app payment flow using Smart2Pay.SDK.Payment, a class designed to make building your app’s checkout flow as easy as possible.

  1. Download the smart2pay.aar file located at: https://github.com/Smart2Pay/SDK-Android-Release/tree/master/releases.
  2. Place the .aar file in the app/libs folder.
  3. Add this to your app Gradle file and click on the Sync Now button.
    dependencies {
        api files('libs/smart2pay.aar')
    }

Now that the SDK is in the app, you can actually use it in the code. Continue with setting up the SDK:

Smart2Pay Mobile SDK

By using Smart2Pay SDK for mobile, you can quickly integrate more payment options directly in your mobile application. Our SDK provides one unique interface to Cards, Alipay and WeChat in-app payments.

You can download our mobile SDK for Android and iOS together with demo projects from Github:

For Alipay and Wechat, the payments are initiated by the user from the mobile app and the initial message is sent by your server to our REST API in the usual way (see Create a payment), plus sending an additional parameter IsMobileApp: true. We will respond back with the Instructions field that needs to be passed from your app to our SDK. Our SDK handles the various calls to Alipay or WeChat apps and returns the control to your app for the final verification of the status.

Besides Alipay and WeChat, our Mobile SDK can be used for in-app purchases using Credit Cards. The advantage of using our SDK is that the credit card details never reach your server, simplifying to a minimum the PCI requirements you must meet.

For more details regarding the installation and the configuration of the SDK, please go to the below sections:

Tingg Test Data

In order for you to test Tingg payment method available in Nigeria, please use the below test data.

Tingg (Nigeria) Test Data
Data Value
Phone 23485844338

Tingg (Nigeria) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives all the details needed to complete the payment.

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

NIBSS Test Data

In order for you to test NIBSS payment method available in Nigeria, please use the below test data.

NIBSS (Nigeria) Test Data
Data Value
Phone 23485844338

NIBSS (Nigeria) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives all the details needed to complete the payment.

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

PesaLink (Kenya) Test Data

In order for you to test PesaLink payment method available in Kenya, please use the below test data.

PesaLink (Kenya) Test Data
Data Value
Phone 255653560949

PesaLink (Kenya) Payment Flow

  1. The customer fills in his personal details, including: his first and last name, email address and phone number. Then, the customer chooses the desired bank from the provided list.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

M-Pesa (Ghana) Test Data

In order for you to test M-Pesa payment method available in Ghana, please use the below test data.

M-Pesa (Ghana) Test Data
Data Value
Phone 02092332540

M-Pesa (Ghana) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

MTN (Ghana) Test Data

In order for you to test MTN payment method available in Ghana, please use the below test data.

MTN (Ghana) Test Data
Data Value
Phone 04517108710

MTN (Ghana) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

MTN Test Data

In order for you to test MTN payment method available in Uganda, please use the below test data.

MTN Test Data
Data Value
Phone 256387676229

For MTN payment method available in Ghana, you can see how it works with the payment flow given here: MTN (Ghana) Payment Flow.

MTN (Uganda) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Tigo Pesa Test Data

In order for you to test Tigo Pesa payment method available in Ghana, please use the below test data.

Tigo Pesa (Ghana) Test Data
Data Value
Phone 02787560500

Tigo Pesa (Ghana) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Equitel Test Data

In order for you to test Equitel payment method available in Kenya, please use the below test data.

Equitel (Kenya) Test Data
Data Value
Phone 254725362916

Equitel (Kenya) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Airtel Money (Uganda) Test Data

In order for you to test Airtel Money payment method available in Uganda, please use the below test data.

Airtel Money (Uganda) Test Data
Data Value
Phone 256428789696

Airtel Money (Uganda) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Airtel Money (Ghana) Test Data

In order for you to test Airtel Money payment method available in Ghana, please use the below test data.

Airtel Money (Ghana) Test Data
Data Value
Phone 02622595320

Airtel Money (Ghana) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Airtel Money (Kenya) Test Data

In order for you to test Airtel Money payment method available in Kenya, please use the below test data.

Airtel Money (Kenya) Test Data
Data Value
Phone 254725362916

Airtel Money (Kenya) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

Airtel Money Test Data

In order for you to test Airtel Money payment method available in Tanzania, please use the below test data.

Airtel Money (Tanzania) Test Data
Data Value
Phone 255737306783

Please click on the appropriate link below, to see how Airtel Money payment method works in Kenya, Ghana and Uganda:

Airtel Money (Tanzania) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

M-Pesa (Tanzania) Test Data

In order for you to test M-Pesa payment method available in Tanzania, please use the below test data.

M-Pesa (Tanzania) Test Data
Data Value
Phone 255653560949

M-Pesa (Tanzania) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is a success

M-Pesa Test Data

In order for you to test M-Pesa payment method, please use the below test data.

M-Pesa Test Data
Data Value
Phone 254716737623

Please click on the appropriate link below, to see how M-Pesa payment method works in Tanzania and Ghana:

  1. M-Pesa (Tanzania) Payment Flow;
  2. M-Pesa (Ghana) Payment Flow.

M-Pesa (Kenya) Payment Flow

  1. The customer fills in his first and last name, his email address and his phone number.

    1 Payment instructions

  2. The customer receives the details needed to complete the payment.

    1 Payment instructions

  3. The customer receives a push notification to his mobile and confirms the payment.

    1 Payment instructions

  • In case the customer has not received the M-Pesa prompt on his phone, there is another possibility to complete a M-Pesa payment flow by following the instructions:
  1. The customer opens the SIM Tool Kit and selects “M-Pesa” menu.

    1 Payment instructions

  2. The customer selects “Lipa na M-Pesa”.

    1 Payment instructions

  3. The customer selects the “Pay Bill” option.

    1 Payment instructions

  4. The customer enters his business number.

    1 Payment instructions

  5. The customer enters his account number.

    1 Payment instructions

  6. The customer needs to enter the amount.

    1 Payment instructions

  7. The customer needs to enter his M-Pesa PIN number and press “OK” button to complete the payment.

    1 Payment instructions

  8. The customer receives the payment details. If the details are correct he needs to press “OK” button to confirm the payment.

    1 Payment instructions

WeChat POS Test Data

For WeChat payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

WeChat POS Payment Flow

  1. The customer selects his preferred currency from the list and enters his email address.

    1 Enter email

  2. You can skip this step by sending in the initial POST the following parameters: SkipHPP=1 and CustomerEmail.

  3. The Customer is redirected to WeChat payment page.

    1 WeChat payment page

  4. The Customer opens WeChat application and scans the QR code.

    1 QR code scanning

  5. The payment details are displayed and the customer confirms by using the payment password.

    1 Payment confirmation

  6. The payment is confirmed.

    1 Payment successful

  7. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is Processing

Alipay POS Test Data

For Alipay payment method there aren’t any test data available, but you can see how it works with the payment flow given below.

Alipay POS Payment Flow

    1. The Customer selects his preferred currency from the list and continues the payment.

      1 Select currency

You can skip this step by sending in the initial POST the following parameters: SkipHPP=1 and CustomerEmail.

  1. The Customer is redirected to Alipay payment page. The Customer opens Alipay application and scans the QR code.

    1 Payment version

  2. The payment details are displayed and the customer confirms the payment.

    1 Payment confirmation

  3. Upon completion of the payment flow, the customer is redirected back to your ReturnURL.

    1 Return page when the redirection status is Processing

WeChat POS Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for WeChat POS method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

For WeChat POS payments the IsOffline parameter set to true is mandatory to be sent in the request:

  • IsOffline – Offline payment method;

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request: 

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_k2",
    "Amount": 11,
    "Currency": "CNY",      
    "MethodID": 1066,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "BillingAddress": {
      "Country": "CN"
      }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": 4116540,
    "SkinID": null,
    "ClientIP": null,
    "Created": "20181009113622",
    "MerchantTransactionID": "s2ptest_k2",
    "OriginatorTransactionID": null,
    "Amount": "11",
    "Currency": "CNY",
    "CapturedAmount": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": "",
    "MethodID": 1066,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": 30201,
    "NotificationDateTime": null,
    "Customer": {
      "ID": 340,
      "MerchantCustomerID": null,
      "Email": "youremail@email.com",
      "FirstName": null,
      "LastName": null,
      "Gender": null,
      "SocialSecurityNumber": null,
      "SocialSecurityNumber2": null,
      "Phone": null,
      "Company": null,
      "DateOfBirth": null
      },
    "BillingAddress": {
      "ID": 291,
      "City": null,
      "ZipCode": null,
      "State": null,
      "Street": null,
      "StreetNumber": null,
      "HouseNumber": null,
      "HouseExtension": null,
      "Country": "CN"
      },
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": {
      "BankCode": null,
      "BankName": null,
      "EntityID": null,
      "EntityNumber": null,
      "ReferenceID": null,
      "ReferenceNumber": null,
      "SwiftBIC": null,
      "AccountCurrency": null,
      "AccountNumber": null,
      "AccountHolder": null,
      "IBAN": null,
      "QRCodeURL": "weixin://wxpay/bizpayurl?pr=qXY38eE",
      "Instructions": null
      },
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": 1,
      "Info": "Open",
      "Reasons": null
      },
    "MethodTransactionID": null,
    "TokenLifetime": 10,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=73EF92D30E6E3D90ED2E9FE4A9238FC3.4116540"
  }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section GlobalPay Return Codes.

Request:

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_k4",
    "Amount": 11,
    "Currency": "CN",      
    "MethodID": 1066,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "BillingAddress": {
      "Country": "CN"
    }
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payment": {
    "ID": null,
    "SkinID": null,
    "ClientIP": null,
    "Created": null,
    "MerchantTransactionID": "s2ptest_k4",
    "OriginatorTransactionID": null,
    "Amount": "11",
    "Currency": "CN",
    "CapturedAmount": null,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",
    "Description": null,
    "MethodID": 1066,
    "MethodOptionID": null,
    "IncludeMethodIDs": null,
    "ExcludeMethodIDs": null,
    "PrioritizeMethodIDs": null,
    "SiteID": null,
    "NotificationDateTime": null,
    "Customer": null,
    "BillingAddress": null,
    "ShippingAddress": null,
    "Articles": null,
    "Details": null,
    "ReferenceDetails": null,
    "CustomParameters": null,
    "PreapprovalID": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
      {
        "Code": 2,
        "Info": "Validation failed - Currency (RegEx: ^[A-Z]{3}$)"
        }
      ]
    },
    "MethodTransactionID": null,
    "TokenLifetime": null,
    "Capture": null,
    "PreapprovalDetails": null,
    "RedirectURL": null
  }
}

Alipay POS Payment Request

Definition: POST https://paytest.smart2pay.com/v1/payments

Below you will find a full example of a payment request for Alipay POS method (with Success and Bad response). The parameters of the payment are sent in the message body as a JSON object.

For Alipay POS payments the following Details parameters are mandatory to be sent in the request:

  • IsOffline – Offline payment method;
  • StoreName – Store name. Can be null only when the store information is verified;
  • StoreId – Store ID;
  • TerminalID – POS Terminal ID.

A 201 HTTP response (Created) is returned if the payment was correctly initialized.

For more information about status codes, please go to Basic HTTP Status Codes.

Request:

POST https://paytest.smart2pay.com/v1/payments
Authorization: Basic MzAyMDE6aEo1Um9iWXg5cjdGZk53Q3ZIWTlMWEhxcXIrRkV6cmM3YUp2UVFrNEdhejFtZzdSeXk=

{
  "Payment": {
    "MerchantTransactionID": "s2ptest_k11",
    "Amount": 11,
    "Currency": "CNY",      
    "MethodID": 24,
    "ReturnURL": "http://demo.smart2pay.com/redirect.php",      
    "TokenLifetime": 10,
    "Customer": {    
      "Email": "youremail@email.com"   
    },
    "BillingAddress": {
      "Country": "CN"
      },
    "Details": {    
      "IsOffline": true,
      "StoreName": "Zara Palace Mall",
      "StoreId": "ZA2345",
      "TerminalID": "T8999"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
    "Payment": {
        "ID": 4710714,
        "SkinID": null,
        "ClientIP": null,
        "Created": "20190715075533",
        "MerchantTransactionID": "s2ptest_k11",
        "OriginatorTransactionID": null,
        "Amount": "11",
        "Currency": "CNY",
        "CapturedAmount": null,
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "",
        "MethodID": 24,
        "MethodOptionID": null,
        "IncludeMethodIDs": null,
        "ExcludeMethodIDs": null,
        "PrioritizeMethodIDs": null,
        "SiteID": 30201,
        "NotificationDateTime": null,
        "Customer": {
            "MerchantCustomerID": null,
            "Email": "youremail@email.com",
            "FirstName": null,
            "LastName": null,
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 291,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "CN"
        },
        "ShippingAddress": null,
        "Articles": null,
        "Details": {
            "AccountNumber": null,
            "AccountHolder": null,
            "IBAN": null,
            "BIC": null,
            "PrepaidCard": null,
            "PrepaidCardPIN": null,
            "SerialNumbers": null,
            "Wallet": null,
            "ReferenceNumber": null,
            "PayerCountry": null,
            "PayerEmail": null,
            "PayerPhone": null,
            "BankCode": null,
            "BankName": null,
            "BankSortCode": null,
            "SocialSecurityNumber": null,
            "BillingCycleStart": null,
            "BillingCycleEnd": null,
            "UnsubscribeInstructions": null,
            "CustomerLoginID": null,
            "PaidAmount": null,
            "PaidCurrency": null,
            "ProviderExchangeRate": 0,
            "PayerBankAccountID": null
        },
        "ReferenceDetails": {
            "BankCode": null,
            "BankName": null,
            "EntityID": null,
            "EntityNumber": null,
            "ReferenceID": null,
            "ReferenceNumber": null,
            "SwiftBIC": null,
            "AccountCurrency": null,
            "AccountNumber": null,
            "AccountHolder": null,
            "IBAN": null,
            "AmountToPay": null,
            "QRCodeURL": "https://qr.alipay.com/bax04298omdb9ssnjhk560db",
            "Instructions": null,
            "BoletoURL": null
        },
        "CustomParameters": null,
        "PreapprovalID": null,
        "Status": {
            "ID": 1,
            "Info": "Open",
            "Reasons": null
        },
        "Fraud": null,
        "MethodTransactionID": null,
        "TokenLifetime": 10,
        "Capture": null,
        "PreapprovalDetails": null,
        "RedirectURL": "https://apitest.smart2pay.com/Home?PaymentToken=22291D163D2F51BAAFA72C9B9A852D03.4710714"
    }
}