Update customer cards

Improve acceptance rates by keeping your customer’s payment method updated. For example, card expiry.

Update CardSet Default CardRemove CardHosted

API example

Update Card


POST  /acceptor/rest/customers/{instId}/{custId}/paymentMethods/{token}/update
{
  "card": {
    "validDate": "1111"
  },
  "isPrimary": "true",
  "billingAddress": {
    "line1": "New Line 1 of Address"
  }
}

HTTP/1.1 201
{
  "billingAddress": {
    "city": "Bath",
    "country": "United Kingdom",
    "countryCode": "GBR",
    "line1": "Flat 4 ",
    "line2": "Cauldron house",
    "line3": "A Street",
    "line4": "Twertonia",
    "name": null,
    "postcode": "BA1 234",
    "region": "Somerset"
  },
  "card": {
    "cardHolderName": "John Smith",
    "cardNickname": "John",
    "cardToken": "MT_lBWm_3wITvmm5b7sjCaSiA",
    "cardType": "MC_DEBIT",
    "cardUsageType": "DEBIT",
    "cardScheme": "VISA",
    "expiryDate": "0115",
    "issueNumber": "1112",
    "issuer": "Lloyds",
    "issuerCountry": "GBR",
    "maskedPan": "544157******0008",
    "validDate": "1111"
  },
  "isPrimary": true,
  "link": [
    {
      "href": "http://localhost:8080/acceptor/rest/manage/1009/customers/1/paymentMethods/MT_lBWm_3wITvmm5b7sjCaSiA",
      "rel": "self"
    },
    {
      "href": "http://localhost:8080/acceptor/rest/manage/1009/customers/1/paymentMethod/MT_lBWm_3wITvmm5b7sjCaSiA/remove",
      "rel": "remove"
    },
    {
      "href": "http://localhost:8080/acceptor/rest/manage/1009/customers/1",
      "rel": "customer"
    },
    {
      "href": "http://localhost:8080/acceptor/rest/manage/1009/customers/1/paymentMethods/MT_lBWm_3wITvmm5b7sjCaSiA/update",
      "rel": "update"
    },
    {
      "href": "http://localhost:8080/acceptor/rest/manage/1009/customers/1/paymentMethod/MT_lBWm_3wITvmm5b7sjCaSiA/makeDefault",
      "rel": "make-primary"
    }
  ],
  "paymentClass": "CARD"
}

API endpoint

endpoint: /acceptor/rest/customers/{instId}/{customerId}/paymentMethods/{token}/update

method: POST

summary: Update Card

parameters:

instId

string

The installation id

customerId

string

The customer id

token

string

token

request body:

{
isPrimary	boolean Indicates if the card being used should become the Customer’s default card.
card {	Use if you are updating card details.
issueNumber	number The issue number for the card.
expiryDate	string The expiry date for the card.
validDate	string The valid from date of the card. Formatted as MMYY.
cardNickname	string The name the Customer provides for their card to allow easy selection where they register multiple cards.
}
billingAddress {	The billing address of the Customer. Will be used for AVS checks.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}

response:

{
paymentClass	string The classification of payment method used. Eg. Card, Cash, PayPal
isPrimary	boolean Indicates if this was Customer’s primary registered payment method.
card {
issueNumber	string The issue number of the card used in the request.
cardToken	string The token for the card.
cardHolderName	string The Cardholder’s name.
issuer	string The Issuer of the card.
maskedPan	string The masked card number. eg. 123456******1234
issuerCountry	string The country of the card Issuer.
expiryDate	string The expiry date of the card. Formatted as MMYY.
validDate	string The valid from date of the card. Formatted as MMYY.
cardType	string The type of card. Eg. MC_DEBIT, VISA_CREDIT, AMEX.
cardUsageType	string The usage type of card. Eg. DEBIT, CREDIT.
cardScheme	string The scheme of card. Eg. VISA, MASTERCARD, AMEX.
cardCategory	string The category of card. Eg. CREDIT, DEBIT, CORPORATE, BUSINESS.
cardNickname	string string The name the Customer provided for their Card to allow easy selection where they registered multiple cards.
}
billingAddress {	The billing address of the Customer. Will be used for AVS checks.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
country	string Country name of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}

API example

Set Default Card


POST /acceptor/rest/customers/{instId}/{customerId}/paymentMethod/{token}/makeDefault
{}

HTTP/1.1 201
{
  "paymentClass": "CARD",
  "card": {
    "cardToken": "MT_hkuJIGioTy-4T_9hhNTzGw",
    "cardType": "VISA_DEBIT",
    "cardUsageType": "DEBIT",
    "cardScheme": "VISA",
    "maskedPan": "100035******0007",
    "expiryDate": "0315",
    "issuer": "DATACASH",
    "issuerCountry": "GBR",
    "cardHolderName": "John Smith",
    "cardNickname": "John",
    "validDate": "1111"
  },
  "isPrimary": true,
  "billingAddress": {
    "line1": "Flat 1 ",
    "line2": "Cauldron house",
    "line3": "A Street",
    "line4": "Twertonia",
    "city": "Bath",
    "region": "Somerset",
    "postcode": "BA1 234",
    "country": "United Kingdom",
    "countryCode": "GBR"
  },
  "link": [
    {
      "rel": "self",
      "href": "http://localhost:8080/acceptor/rest/customers/1009/10500/paymentMethods/MT_hkuJIGioTy-4T_9hhNTzGw"
    },
    {
      "rel": "remove",
      "href": "http://localhost:8080/acceptor/rest/customers/1009/10500/paymentMethod/MT_hkuJIGioTy-4T_9hhNTzGw/remove"
    },
    {
      "rel": "customer",
      "href": "http://localhost:8080/acceptor/rest/customers/1009/10500"
    },
    {
      "rel": "update",
      "href": "http://localhost:8080/acceptor/rest/customers/1009/10500/paymentMethods/MT_hkuJIGioTy-4T_9hhNTzGw/update"
    },
    {
      "rel": "make-primary",
      "href": "http://localhost:8080/acceptor/rest/customers/1009/10500/paymentMethod/MT_hkuJIGioTy-4T_9hhNTzGw/makeDefault"
    }
  ]
}

API endpoint

endpoint: /acceptor/rest/customers/{instId}/{customerId}/paymentMethod/{token}/makeDefault

method: POST

summary: Set Default Card

parameters:

instId

string

The installation id

customerId

string

The customer id

token

string

token

response:

{
paymentClass	string The classification of payment method used. Eg. Card, Cash, PayPal
isPrimary	boolean Indicates if this was Customer’s primary registered payment method.
card {
issueNumber	string The issue number of the card used in the request.
cardToken	string The token for the card.
cardHolderName	string The Cardholder’s name.
issuer	string The Issuer of the card.
maskedPan	string The masked card number. eg. 123456******1234
issuerCountry	string The country of the card Issuer.
expiryDate	string The expiry date of the card. Formatted as MMYY.
validDate	string The valid from date of the card. Formatted as MMYY.
cardType	string The type of card. Eg. MC_DEBIT, VISA_CREDIT, AMEX.
cardUsageType	string The usage type of card. Eg. DEBIT, CREDIT.
cardScheme	string The scheme of card. Eg. VISA, MASTERCARD, AMEX.
cardCategory	string The category of card. Eg. CREDIT, DEBIT, CORPORATE, BUSINESS.
cardNickname	string The name the Customer provided for their Card to allow easy selection where they registered multiple cards.
}
billingAddress {	The billing address of the Customer. Will be used for AVS checks.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
country	string Country name of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}

API example

Remove Card


POST /acceptor/rest/customers/{instId}/{customerId}/paymentMethod/{token}/remove
{}

HTTP/1.1 201
Customer payment method successfully removed

API endpoint

endpoint: /acceptor/rest/customers/{instId}/{customerId}/paymentMethod/{token}/remove

method: POST

summary: Remove Card

parameters:

instId

string

The installation id

customerId

string

The customer id

token

string

token

response:

Customer payment method successfully removed

Hosted examples

Create a Hosted session to allow the user to manage their cards


POST /hosted/rest/sessions/{instId}/cards
{
  "session": {
    "returnUrl": {
      "url": "http://www.example.com/customerResult?CUSTOMERREF=1111111111111"
    }
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "1111111111111"
    }
  }
}

HTTP/1.1 200
{
  "sessionId": "12c198cc-ef5c-4361-8bb3-b97c3e95b126",
  "redirectUrl": "http://www.paypoint.net/hosted/0ba23e53-894e-4a93-9691-9d303b3c1d02/begin/12c198cc-ef5c-4361-8bb3-b97c3e95b126",
  "status": "SUCCESS"
}

Hosted endpoint

endpoint: /hosted/rest/sessions/{instId}/cards

method: POST

summary: Create a Hosted session to allow the user to manage their cards

parameters:

instId

string

The installation id

request body:

{
customer {	Mandatory
identity {	Mandatory
platformCustomerId	string Choice Our ID for your customer.
merchantCustomerId	string Choice Your ID for the customer.
}
}
locale	string The ISO-639 code for your Customer’s locale.
session {	Mandatory
returnUrl {	Mandatory The URL that we will return your customer to after processing the transaction.
url	string Mandatory
}
skin	string The ID of the skin used to drive look and feel for this session. Refer to Customise hosted look and feel for more information.
}
}

response:

{
sessionId	string Our ID for the hosted session.
redirectUrl	string The URL you should direct your customer to to start the hosted session.
status	string Possible Values: SUCCESS, FAILED<br/ >Indicates the status of the session creation.
reasonCode	string Further information about the status of the session creation.
reasonMessage	string Further information about the status of the session creation. This is where we will provide detailed information about any errors.
}

Developer Documents