Transfer card mapping notification

Introduction

Transfer card mapping notification is initiated through HTTPS POST request by using URLs and the parameters.
Card mapping notification is used to allow Consumer credentials (phone, email, billing address, twitter name, etc) for mapping to card data. Card mappings can be used later in transfer or sale transactions instead of card numbers and other cardholder information. GitPay sends Transfer card mapping notification request to Connecting Party’s server/proxy with created on its side card reference - {serverCardId}.
Connecting Party’s server maps this {serverCardId} to {clientCardId}, created on its side. This {clientCardId} can then be mapped in Connecting Party’s app or on Connecting Party’s server to any Consumer’s data from the initial Perform transfer request. This allows Connecting Party’s app to process sale or transfer transactions by Consumer’s email, phone number, etc.
{uniqueReferenceCardId} remains the same if Consumer makes another verification with the same card number but different expiry date, for example. It can be used by Connecting Party for loyalty programs or fraud control.
Connecting Party’s app makes new transfer requests using {clientCardId} instead of source or destination card data. GitPay sends this {clientCardId} to Connecting Party’s server in “Check transfer request” and gets mapped to it {serverCardId} in “Check transfer response” from Connecting Party’s server, which is used to continue processing the transfer transaction.
{serverCardId} of source or verified card can be used both as source or destination for new transfer and sale transactions; {serverCardId} of destination card can be used only as destination for new transfers.

API URLs

Connecting Party Server
https://proxy.connectingpartyserver.com/transfer/notification

Request Parameters

Parameter Name	Description	Value
consumer		`Necessity`: Required `Type`: Object
consumer.device		`Necessity`: Required `Type`: Object
consumer.device.serialNumber	Consumer’s device serial number.	`Necessity`: Required `Type`: String `Length`: 1-50
session		`Necessity`: Required `Type`: Object
session.accessToken	Consumer’s access token key.	`Necessity`: Required `Type`: String `Length`: 32-128
session.token	The session token of transfer transaction.	`Necessity`: Required `Type`: String `Length`: 16-36
destinationCard		`Necessity`: Optional `Type`: Object
destinationCard.bin	The Destination card BIN.	`Necessity`: Optional `Type`: Integer
destinationCard.reference		`Necessity`: Optional `Type`: Object
destinationCard.reference.serverCardId	The Destination card reference identifier (on server side).	`Necessity`: Optional `Type`: String `Length`: 1-64
destinationCard.reference.uniqueReferenceCardId	The Destination card unique identifier (on server side).	`Necessity`: Optional `Type`: Integer
sourceCard		`Necessity`: Optional `Type`: Object
sourceCard.bin	The Source card BIN.	`Necessity`: Optional `Type`: Integer
sourceCard.reference		`Necessity`: Optional `Type`: Object
sourceCard.reference.serverCardId	The Source card reference identifier (on server side).	`Necessity`: Optional `Type`: String `Length`: 1-64
sourceCard.reference.uniqueReferenceCardId	The Source card unique identifier (on server side).	`Necessity`: Optional `Type`: Integer

Success Response Parameters

Parameter Name	Description	Value
invoiceId	Transfer transaction identifier.	`Type`: String
session		`Type`: Object
session.checkSignature	Checksum generated by hmac-sha1 (see Signature computation) from the concatenation of session.nonce, endpointId and invoiceId.	`Type`: String
session.nonce	Unique random string generated by Connecting Party’s server.	`Type`: String
session.token	The session token of transfer transaction.	`Type`: String

Fail Response Parameters

Parameter Name	Description	Value
error		`Type`: Object
error.cause	Сause of the error. Possible values: `FILTERED`, `INVALID_REQUEST`, `SERVER_FAILED`, `SERVER_UNAVAILABLE`.	`Type`: Enum
error.code	The unique error code.	`Type`: String
error.message	Description of the error.	`Type`: String
invoiceId	Transfer transaction identifier.	`Type`: String

Request Example

{
  "consumer": {
    "device": {
      "serialNumber": "string"
    }
  },
  "destinationCard": {
    "bin": "integer",
    "reference": {
      "serverCardId": "string",
      "uniqueReferenceCardId": "integer"
      }
    },
  "session": {
    "accessToken": "string",
    "token":"string"
  },
  "sourceCard": {
    "bin": "integer",
    "reference": {
      "serverCardId": "string",
      "uniqueReferenceCardId": "integer"
    }
  }
}

Success Response Example

{
  "invoiceId": "string",
  "session": {
    "checkSignature": "string",
    "nonce": "string",
    "token": "string"
  }
}

Fail Response Example

{
  "error": {
    "cause": "enum",
    "code": "string",
    "message": "string"
  },
  "invoiceId": "string"
}