Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

Update Billing

Overview

There will come a time where you need to update details stored against a stored token in order o allow for future payments to be made, i.e. Future REBILL and REUSE requests.

Your customer may have lost their card and their issuing bank has updated their cardnumber and exp_date and as such, you need to ensure that you have the latest information on record. To complete this, you must process a UPDATE_BILLING request.

We also allow you to update the customer’s personal details, i.e. billing, shipping and customer data - to complete this, you must utilise the SUBSCRIPTION_MANAGE request.

To complete updating your customer’s token reference, set the subscription_type parameter with the value UPDATE_BILLING. You can see below some sample code to get you started. 


{
    "timestamp":"20201126154545",
    "company_id":"133",
    "company_pass":"password",
    "company_mid_id":"",
    "request_hash":"f0a18260b08a0bfacb...",
    "transaction":{
        "merchant_order_id":"20170612200234",
        "transaction_type":"AUTH_ONLY",
        "original_transaction_id":"1234567",
        "subscription_type":"UPDATE_BILLING",
        "amount":"0",
        "currency_code_iso3":"GBP"
    },
    "billing":{
        "cardholder_name":"MR E N JOHNSON",
        "cardnumber":"4024007164218280",
        "card_type":"VISA",
        "cardcvv":"456",
        "cardexp":"032026"
    }
}

Request Parameters

The table below details the parameters that must be submitted in order to update your token reference - the INIT.

Parameter Format Length Description
subscription_type string 4 - 14 Set value to: UPDATE_BILLING.
Value should be set to UPDATE_BILLING.
Acceptable Characters: a-Z A-Z _

Please see below sample code of an UPDATE_BILLING response.


{
  "timestamp":"20201126154546",
  "response_code":"1",
  "response_message":"Transaction Success",
  "company_id":"133",
  "mid":"1556",
  "transaction_id":"306751",
  "transaction_type":"AUTH_ONLY",
  "merchant_order_id":"20200327131224",
  "amount":"0",
  "currency_code_iso3":"GBP",
  "authorization_code":"123456",
  "acquirer_reference_number":"",
  "avsaddress":"N",
  "avszipcode":"NP",
  "cvvresult":"N",
  "bank_response_code":"00",
  "bin":{
      "issuing_bank":"BANK OF AMERICA",
      "card_category":"CREDIT",
      "card_level":"CLASSIC",
      "issuing_country":"United Kingdom",
      "issuing_country_iso2":"GB"
  },
  "response_hash":"3fa4e02f4cc4e5d4cb70099c732d8aeb122d9bb1ad5977ce21d8b8deb4e9bd13"
}

Reponse Parameters

The table below details the parameters that will be returned from your update billing request:

Parameter Format Length Description
timestamp date 14 Date and time of transaction response.
response_code int 3 Code describing the transaction result.
response_message string 1-100 Text describing the transaction response.
company_id int 1-11 API Company ID we issue to merchants.
mid string 1-11 MID_ID the transaction was processed through.
transaction_id int 1-10 Unique ID we generate to identify the transaction.
transaction_type string 1-12 Transaction type, repeated from the request message.
merchant_order_id string 1-50 Unique ID you’ll use to identify each transaction, repeated from the request.
amount string 1-11 Transaction amount.
currency_code_iso3 string 3 Transaction currency, an ISO 4217 3-digit code.
authorization_code string 0-50 Authorisation code returned by the issuing bank.
acquirer_reference_number string 0-50 Value set by the acquirer to track the transaction, when present.
avsaddress string 1-2 AVS check on the first line of the customer’s address, when available.
avszipcode string 1-2 AVS check on the customer’s postcode or zipcode, when available.
cvvresult string 1-2 Result of CVV2 security check.
bank_response_code int 2 Transaction result code communicated by the issuing bank.
bin object
issuing_bank string 0-50 Name of the bank issuing the card used for the transaction.
card_category string 0-30 Category of the card used, for example CREDIT or DEBIT.
card_level string 0-30 Level of the card used, for example CLASSIC.
issuing_country string 0-50 Country issuing the card used for the transaction.
issuing_country_iso2 string 2 Country issuing the card used for the transaction, an ISO2 two-letter code.
response_hash string 64 Verification hash value.
You can proactively update your customer’s card using Account Updater. We allow you to request updated details on an adhoc basis or we can handle everything for you. Please see here for more info.