KakaoPay Preapproval Request – Nuvei Documentation

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 KakaoPay (1135).

Request:

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

{
 "Preapproval": {
   "MerchantPreapprovalID": "s2ptest_kAKAOPAY_PreapprovalS1",
   "Currency": "KRW",
   "Description": "1 year subscription",
   "ReturnURL": "http://demo.smart2pay.com/redirect.php",
   "MethodID": 1135,
   "Customer": {
      "FirstName": "John",
      "LastName": "Doe",
      "Email": "jdoe@gmail.com"
     },
   "BillingAddress": {
      "Country": "KR"
      }
   }
}

{"Preapproval":{"hint":"Preapproval structure","regexp":"","type":"object","MerchantPreapprovalID":{"hint":"Merchant Preapproval ID, a number that uniquely identifies a preapproval in your system.","regexp":"","type":"string"},"MethodID":{"hint":"The ID of the payment method.","regexp":"^\\d{1,12}$","type":"int"},"MethodOptionID":{"hint":"The ID of the payment option; can be used when the payment method has multiple payment options (e.g. ING bank is an option for iDEAL).","regexp":"^([0-9]{1,10})$","type":"int"},"ExecutionDate":{"hint":"Executed at a specific date","regexp":"","type":"date"},"RecurringPeriod":{"hint":"Preapproval recurring period","regexp":"^\\d{1,12}$","type":"int"},"Description":{"hint":"Text describing the subscription sold; will be displayed on the automatic debit confirmation page.","regexp":"^.{1,255}$","type":"string"},"PreapprovedMaximumAmount":{"hint":"Preapproval maximum amount. Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"ReturnURL":{"hint":"An URL where the customer will be redirected after the approval process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}}}}

Response:

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

{
    "Preapproval": {
        "ID": 22276,
        "Created": "20200331063928",
        "MethodID": 1135,
        "SiteID": 30597,
        "MerchantPreapprovalID": "s2ptest_kAKAOPAY_PreapprovalS1",
        "RecurringPeriod": 0,
        "PreapprovedMaximumAmount": null,
        "Currency": "KRW",
        "ReturnURL": "http://demo.smart2pay.com/redirect.php",
        "Description": "1 year subscription",
        "Customer": {
            "ID": 2622497,
            "MerchantCustomerID": null,
            "Email": "jdoe@gmail.com",
            "FirstName": "John",
            "LastName": "Doe",
            "Gender": null,
            "SocialSecurityNumber": null,
            "Phone": null,
            "Company": null,
            "DateOfBirth": null
        },
        "BillingAddress": {
            "ID": 657,
            "City": null,
            "ZipCode": null,
            "State": null,
            "Street": null,
            "StreetNumber": null,
            "HouseNumber": null,
            "HouseExtension": null,
            "Country": "KR"
        },
        "Status": {
            "ID": 1,
            "Info": "Pending",
            "Reasons": null
        },
        "RedirectURL": "https://europaytest.smart2pay.com/AlipayOSP/Preapproval/PreapprovalLanding.aspx?ID=17598&Hash=64B81EAA7FE00CB58E187BE0615CC7BD",
        "MethodOptionID": 0,
        "PreapprovedFrequency": null,
        "MandateReference": null,
        "Details": null
    }
}

{"Preapproval":{"hint":"Preapproval structure","regexp":"","type":"object","ID":{"hint":"GlobalPay preapproval ID, a unique number that identifies the preapproval in the GlobalPay system; you will need to store this id in order to initiate recurring payments.","regexp":"^\\d{1,12}$","type":"int"},"Created":{"hint":"Date and time when the preapproval was created.","regexp":"","type":"datetime"},"MethodID":{"hint":"The ID of the payment method.","regexp":"^\\d{1,12}$","type":"int"},"SiteID":{"hint":"The ID of the site","regexp":"^\\d{1,12}$","type":"int"},"MerchantPreapprovalID":{"hint":"Merchant Preapproval ID, a number that uniquely identifies a preapproval in your system.","regexp":"","type":"string"},"RecurringPeriod":{"hint":"Preapproval recurring period","regexp":"^\\d{1,12}$","type":"int"},"PreapprovedMaximumAmount":{"hint":"Preapproval maximum amount. Please be aware that data type string is also accepted as long as it contains only digits.","regexp":"^\\d{1,12}$","type":"int"},"Currency":{"hint":"The currency in which you sell the services or products. Format is according to ISO 4217, a three-letter code.","regexp":"^[A-Z]{3}$","type":"string"},"ReturnURL":{"hint":"An URL where the customer will be redirected after the approval process ends.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"Description":{"hint":"Text describing the subscription sold; will be displayed on the automatic debit confirmation page.","regexp":"^.{1,255}$","type":"string"},"Customer":{"hint":"Customer details","regexp":"","type":"object","ID":{"hint":"Customer ID, a unique number that identifies the customer in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"MerchantCustomerID":{"hint":"The ID of the customer in your system.","regexp":"^([0-9a-zA-Z_-]{1,50})?$","type":"string"},"Email":{"hint":"Customer\u2019s email","regexp":"^[a-zA-Z0-9\\._%+-]{1,100}@[a-zA-Z0-9\\.-]{1,40}\\.[a-zA-Z]{1,8}$","type":"string"},"FirstName":{"hint":"Customer\u2019s first name","regexp":"","type":"string"},"LastName":{"hint":"Customer\u2019s last name","regexp":"","type":"string"},"Gender":{"hint":"Customer\u2019s gender. It can have the following values: 1 - Male, 2 - Female.","regexp":"","type":"string"},"DateOfBirth":{"hint":"Customer date of birth","regexp":"^(((19|20)\\d\\d)(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01]))$","type":"date"},"SocialSecurityNumber":{"hint":"Customer\u2018s social or fiscal identifier","regexp":"","type":"string"},"Phone":{"hint":"Customer\u2019s phone including prefix","regexp":"","type":"string"},"Company":{"hint":"Company name (for legal entities)","regexp":"","type":"string"},"InputDateTime":{"hint":"Customer creation date","regexp":"","type":"datetime"}},"BillingAddress":{"hint":"Billing Address details","regexp":"","type":"object","ID":{"hint":"Address ID, a unique number that identifies an address in the GlobalPay system.","regexp":"^\\d{1,12}$","type":"int"},"Country":{"hint":"Customer\u2018s country. Recommended to be sent in order to increase the conversion. If MethodID is missing, this field (taken from BillingAddress object) controls which payment methods are shown on the hosted payment pages. Format is according to ISO-3166-1 alpha-2, a two-letter code.","regexp":"^([A-Za-z]{2})?$","type":"string"},"City":{"hint":"City name","regexp":"^(.{1,255})?$","type":"string"},"ZipCode":{"hint":"Postal code","regexp":"^(.{1,255})?$","type":"string"},"State":{"hint":"State name","regexp":"^(.{1,255})?$","type":"string"},"Street":{"hint":"Street name","regexp":"^(.{1,255})?$","type":"string"},"StreetNumber":{"hint":"Street Number","regexp":"^(.{1,255})?$","type":"string"},"HouseNumber":{"hint":"House Number","regexp":"^(.{1,255})?$","type":"string"},"HouseExtension":{"hint":"House Extension","regexp":"^(.{1,255})?$","type":"string"}},"Status":{"hint":"Preapproval status","regexp":"","type":"object","ID":{"hint":"The ID of the preapproval status. It can have the following values: 1 - Pending, 2 - Open, 4 - Closed.","regexp":"","type":"int"},"Info":{"hint":"The description of the status","regexp":"","type":"string"},"Reasons":{"hint":"The reasons why the payment got to this status.","regexp":"","type":"array of objects","Code":{"hint":"The id of the message type transmitted in the response. See our section GlobalPay Return Codes for a complete description.","regexp":"","type":"int"},"Info":{"hint":"The message body","regexp":"","type":"string"}}},"RedirectURL":{"hint":"The URL where you need to redirect the customer in order to approve the automatic debit.","regexp":"^(http(s)?(:\\\/\\\/|%3A%2F%2F).+){1,512}$","type":"string"},"MethodOptionID":{"hint":"The ID of the payment option; can be used when the payment method has multiple payment options (e.g. ING bank is an option for iDEAL).","regexp":"^([0-9]{1,10})$","type":"int"},"PreapprovedFrequency":{"hint":"Preapproved frequency - how often is the customer going to be billed. It can be onetime\/daily\/weekly\/monthly depending on the country and the mobile carrier.","regexp":"","type":"string"},"MandateReference":{"hint":"Preapproval mandate reference","regexp":"","type":"string"}}}

Kakaopay Preapproval Flow

The customer is redirected to KakaoPay page where the user needs to confirm the terms of the payment.
The Customer fills in the 6-digit code received via SMS. For testing purposes, enter any 6 digit number.
The customer confirms the auto-debit user agreement