Deactivating the payment safeguard

Discover how you can deactivate your payment safeguard option

This guide shows you how to retrieve your payment safeguard option then deactivate your option.

Endpoints

Below are all APIs url that you will need for this guide:

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
OCS Inventory	https://api.transatel.com/ocs/inventory/api
OCS Subscriptions	https://api.transatel.com/ocs/subscriptions/api

All Transatel APIs are available through our unique API gateway https://api.transatel.com

1. API Authentication

First thing first, let's get your access token by following the getting started guide!

2. Retrieve the state of the payment safeguard option (optional)

Now that you are authenticated, and you have an access token, let's use it to retrieve the state of the payment safeguard option of one of your subscribers.

To do so, we will use OCS Inventory API.

The below example shows how to retrieve the payment safeguard option for a given subscriber:

curl --location --request GET \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    'https://api.transatel.com/ocs/inventory/api/subscriptions/options/paymentSafeguard?msisdn=33612345678'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber

If successful, the response returned will be as follows:

HTTP/1.1 200 OK
X-TSL-Request-Id: 5fd3913a-899e-426a-b841-d1b707ae4ae3
Content-Type: application/json
{
  "state": "active",
  "cutOff": {
    "limit": 10000,
    "unit": "CENTS",
    "currency": "EUR",
    "spent": 0,
    "reached": false
  },
  "nextRenewalDate": "2023-05-19T13:30:00Z",
  "eligibleStates": [
    "inactive"
  ]
}

A successful response returns a HTTP/1.1 200 OK, with the details of the payment safeguard option. The eligibleStates array contains all possible states you can switch the option to.

3. Deactivate the payment safeguard option

Now that we returned the payment safeguard option, let's try to deactivate the option for this subscriber and verify that the payment safeguard option has been correctly changed to inactive.

To do so, we will use the OCS Subscriptions API.

The below example shows how to change the state of the payment safeguard option:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{ 
      \"bind\": {
        \"msisdn\": \"33612345678\"
      },
      \"source\": \"api\",
      \"state\": \"inactive\",
      \"transactionReference\": \"RX12345ZVGT\"
    }" \
    'https://api.transatel.com/ocs/subscriptions/api/orders/options/paymentSafeguard'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber
state: The target state you want to apply

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
X-TSL-Request-Id: a5a7ed35-2f67-4df9-8164-ae4b224707b3
Content-Type: application/json
{
  "bind": {
    "msisdn": "33612345678"
  },
  "orderReference": "SUBIcuMJjmmcSOhm2i57dsSA",
  "source": "api",
  "status": "done",
  "state": "inactive",
  "submissionDate": "2019-08-24T14:15:22Z",
  "transactionReference": "RX12345ZVGT"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your order was successfully processed and the payment safeguard option state was successfully changed.

What to do next?

Learn more about our OCS APIs by checking their overview & API references: