Creation and update of branch offices

August 08, 2023

Learn how to integrate the creation and update of your merchant’s branch offices.

Through the configuration of the endpoints for the creation and updating of branch offices, you will be able to manage the information of your branch offices in a specific, individual, and centralized way. You do not need to go through the process for each branch office; the integration of these endpoints allows you to configure up to 500 branch offices in a single request.

The flow your will integrate is the following:

Integration process back-end

1. Credential request

You need to contact the sales executive associated with your merchant to obtain the credentials to integrate this service.

You will receive an email with the username and password for you to start integrating this functionality.

Email address credential request

2. Token generation

At this step, it is essential to collect the information of the assigned user and password in a secure way and tokenize this information; you must make a call to our tokenization endpoint.

Javascript
Python
PHP

const url = 'https://api-uat.kushkipagos.com/automation/v1/token';
const options = {
  method: 'GET',
  headers: {USERNAME: 'test', PASSWORD: '6558868', Accept: 'application/json'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api-uat.kushkipagos.com/automation/v1/token"

headers = {
    "USERNAME": "test",
    "PASSWORD": "6558868",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-uat.kushkipagos.com/automation/v1/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "PASSWORD: 6558868",
    "USERNAME: test"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

3. Branch office creation

Now, it is necessary to use the obtained token to start the branch office creation process. With this token, you will need to complete the following steps:

Make a call to our branch creation endpoint. Endpoint for credentials creation.
Complete the Sub Merchant Onboarding Report file, filling in the mandatory and optional fields to document the information of the branch offices you need to create in our system. The Kushki team will proceed to review this information.

Javascript
Python
PHP

const url = 'https://api-uat.kushkipagos.com/automation/v1/branches';
const options = {
  method: 'POST',
  headers: {
    'Authorization ': '',
    'Content-Type': 'application/json',
    Accept: 'application/json, application/xml'
  },
  body: '{"clientType":"KUSHKI MUNDIAL","reportingDate":"01-May-2023","pspTaxId":"20552103816","pspName":"SAC DE TRAUMA","pspCustomerId":"00010040103416507045","pspNotificationEmail":["user@example.com","user2@domain.com"],"branches":[{"currency":"MXN","countryTaxResidency":"MEX","name":"Comercio Eli","companyRegistrationNumber":"484","pspUserEmail":"user@example.com","taxId":"0202020","legalName":"My company","legalEntityType":"Entity example","mcc":1231,"legalRepresentative":[{"firstName":"John","lastName":"Doe","idNumber":"1234","birthDate":"02-May-1990","residencyCountry":"MEX"}],"shareholder":[{"firstName":"John","lastName":"Doe","idNumber":"1234","birthDate":"02-May-1990","residencyCountry":"MEX"}],"AMLRiskCategory":"M","settlementBankCountry":"MEX","settlementBankName":"BBVA","regulatedBusiness":"Y","concurrenceNeeded":"N","url":"https://kushki.com"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api-uat.kushkipagos.com/automation/v1/branches"

payload = {
    "clientType": "KUSHKI MUNDIAL",
    "reportingDate": "01-May-2023",
    "pspTaxId": "20552103816",
    "pspName": "SAC DE TRAUMA",
    "pspCustomerId": "00010040103416507045",
    "pspNotificationEmail": ["user@example.com", "user2@domain.com"],
    "branches": [
        {
            "currency": "MXN",
            "countryTaxResidency": "MEX",
            "name": "Comercio Eli",
            "companyRegistrationNumber": "484",
            "pspUserEmail": "user@example.com",
            "taxId": "0202020",
            "legalName": "My company",
            "legalEntityType": "Entity example",
            "mcc": 1231,
            "legalRepresentative": [
                {
                    "firstName": "John",
                    "lastName": "Doe",
                    "idNumber": "1234",
                    "birthDate": "02-May-1990",
                    "residencyCountry": "MEX"
                }
            ],
            "shareholder": [
                {
                    "firstName": "John",
                    "lastName": "Doe",
                    "idNumber": "1234",
                    "birthDate": "02-May-1990",
                    "residencyCountry": "MEX"
                }
            ],
            "AMLRiskCategory": "M",
            "settlementBankCountry": "MEX",
            "settlementBankName": "BBVA",
            "regulatedBusiness": "Y",
            "concurrenceNeeded": "N",
            "url": "https://kushki.com"
        }
    ]
}
headers = {
    "Authorization ": "",
    "Content-Type": "application/json",
    "Accept": "application/json, application/xml"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-uat.kushkipagos.com/automation/v1/branches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'clientType' => 'KUSHKI MUNDIAL',
    'reportingDate' => '01-May-2023',
    'pspTaxId' => '20552103816',
    'pspName' => 'SAC DE TRAUMA',
    'pspCustomerId' => '00010040103416507045',
    'pspNotificationEmail' => [
        'user@example.com',
        'user2@domain.com'
    ],
    'branches' => [
        [
                'currency' => 'MXN',
                'countryTaxResidency' => 'MEX',
                'name' => 'Comercio Eli',
                'companyRegistrationNumber' => '484',
                'pspUserEmail' => 'user@example.com',
                'taxId' => '0202020',
                'legalName' => 'My company',
                'legalEntityType' => 'Entity example',
                'mcc' => 1231,
                'legalRepresentative' => [
                                [
                                                                'firstName' => 'John',
                                                                'lastName' => 'Doe',
                                                                'idNumber' => '1234',
                                                                'birthDate' => '02-May-1990',
                                                                'residencyCountry' => 'MEX'
                                ]
                ],
                'shareholder' => [
                                [
                                                                'firstName' => 'John',
                                                                'lastName' => 'Doe',
                                                                'idNumber' => '1234',
                                                                'birthDate' => '02-May-1990',
                                                                'residencyCountry' => 'MEX'
                                ]
                ],
                'AMLRiskCategory' => 'M',
                'settlementBankCountry' => 'MEX',
                'settlementBankName' => 'BBVA',
                'regulatedBusiness' => 'Y',
                'concurrenceNeeded' => 'N',
                'url' => 'https://kushki.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json, application/xml",
    "Authorization : ",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

The response will confirm that your request is in process, and you will be notified as soon as the branch offices are created. The system will display the following message:

Branch office creation confirmation

4. Branch office update (optional)

You can use the generated token to activate, deactivate, or modify the information previously configured in the creation of your company’s branch offices. To do so, you can perform the same process performed in the branch office creation.

Now, it is necessary to use the obtained token to update the information of the created branch offices. With this token, you will need to make a call to our branch office update endpoint credential update endpoint.

Javascript
Python
PHP

const url = 'https://api-uat.kushkipagos.com/automation/v1/branches';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: '',
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: '{"reportingDate":"19-May-1977","pspTaxId":"20552103816","pspName":"SAC DE TRAUMA","pspCustomerId":"00010040103416507045","pspNotificationEmail":["user@example.com","user1@domain.com"],"branches":[{"branchId":"20000000107724194000","currency":"COP","name":"Comercio UIO","companyRegistrationNumber":"92929","legalName":"legal name","pspUserEmail":"user@example.com","legalEntityType":"entity","mcc":1231,"legalRepresentative":[{"firstName":"José","lastName":"Ramirez","idNumber":"1123904949292","birthDate":"02-May-2022","residencyCountry":"COL"}],"shareholder":[{"firstName":"Lucio","lastName":"Gutierrez","idNumber":"1721333446567","birthDate":"30-May-2022","residencyCountry":"ECU "}],"AMLRiskCategory":"H","settlementBankCountry":"RUS","settlementBankName":"stl bank name","regulatedBusiness":"Y","concurrenceNeeded":"Y","url":"google.com"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api-uat.kushkipagos.com/automation/v1/branches"

payload = {
    "reportingDate": "19-May-1977",
    "pspTaxId": "20552103816",
    "pspName": "SAC DE TRAUMA",
    "pspCustomerId": "00010040103416507045",
    "pspNotificationEmail": ["user@example.com", "user1@domain.com"],
    "branches": [
        {
            "branchId": "20000000107724194000",
            "currency": "COP",
            "name": "Comercio UIO",
            "companyRegistrationNumber": "92929",
            "legalName": "legal name",
            "pspUserEmail": "user@example.com",
            "legalEntityType": "entity",
            "mcc": 1231,
            "legalRepresentative": [
                {
                    "firstName": "José",
                    "lastName": "Ramirez",
                    "idNumber": "1123904949292",
                    "birthDate": "02-May-2022",
                    "residencyCountry": "COL"
                }
            ],
            "shareholder": [
                {
                    "firstName": "Lucio",
                    "lastName": "Gutierrez",
                    "idNumber": "1721333446567",
                    "birthDate": "30-May-2022",
                    "residencyCountry": "ECU "
                }
            ],
            "AMLRiskCategory": "H",
            "settlementBankCountry": "RUS",
            "settlementBankName": "stl bank name",
            "regulatedBusiness": "Y",
            "concurrenceNeeded": "Y",
            "url": "google.com"
        }
    ]
}
headers = {
    "Authorization": "",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-uat.kushkipagos.com/automation/v1/branches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'reportingDate' => '19-May-1977',
    'pspTaxId' => '20552103816',
    'pspName' => 'SAC DE TRAUMA',
    'pspCustomerId' => '00010040103416507045',
    'pspNotificationEmail' => [
        'user@example.com',
        'user1@domain.com'
    ],
    'branches' => [
        [
                'branchId' => '20000000107724194000',
                'currency' => 'COP',
                'name' => 'Comercio UIO',
                'companyRegistrationNumber' => '92929',
                'legalName' => 'legal name',
                'pspUserEmail' => 'user@example.com',
                'legalEntityType' => 'entity',
                'mcc' => 1231,
                'legalRepresentative' => [
                                [
                                                                'firstName' => 'José',
                                                                'lastName' => 'Ramirez',
                                                                'idNumber' => '1123904949292',
                                                                'birthDate' => '02-May-2022',
                                                                'residencyCountry' => 'COL'
                                ]
                ],
                'shareholder' => [
                                [
                                                                'firstName' => 'Lucio',
                                                                'lastName' => 'Gutierrez',
                                                                'idNumber' => '1721333446567',
                                                                'birthDate' => '30-May-2022',
                                                                'residencyCountry' => 'ECU '
                                ]
                ],
                'AMLRiskCategory' => 'H',
                'settlementBankCountry' => 'RUS',
                'settlementBankName' => 'stl bank name',
                'regulatedBusiness' => 'Y',
                'concurrenceNeeded' => 'Y',
                'url' => 'google.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Authorization: ",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

The response will confirm that your request is in process, and you will be notified as soon as the updates in the requested branch offices have been completed. The system will display the following message:

Confirmation of credential update

5. Request validation

Upon receiving a request to create or update your company’s branch offices, the Kushki team will perform a validation of the information received; in order to approve or reject the request.

6. Notification of the response of the request

In order that you can know the result of the request you have made, we will send you an email indicating if this requirement was approved or rejected. This information will be sent within a response period of 24 hours. In some eventual cases, the response time may be longer than the previously mentioned period of time.
In the email, we will include a summary file, which can be viewed with an expiration of 7 days. This document includes the total number of pending registrations.

The following values will appear in this information:

In process from the investigation
Pending from PSP
Pending

Correo electrónico notificación

Additional recommendations

Remember to review the manuals available on the API reference platform; this information was specially created for your development team:

API branch office manual with the information, so your development team can carry out the integration process.
Branch office creation token guide.
Create a branch office guide.
Update a branch office guide.