Authorize Payment

9. Authorize Payment

The authorize payment request is used to authorize a payment. The API is available at the following path:

End point

[Velocity URL]/mpoint/authorize-payment

Format

text/xml

Authentication

HTTP basic access authentication

9.1 Authorize Request

The payment authorize request is initiated using the payment token returned by Apple Pay after a card is selected for completing the transaction by the user. The expected format of <token> is base-64 encoded string.

Sample Token from Apple Pay after base-64 encode: paymentMethodToken:token:

eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiQWNRd0FFeWhSYzdHdWJleUVHOUJnWEdjNktkaTJ4RjMxazJSMTRqNGZxTUtQRHA4S1VyT0FTNVFFRTIxT1U2a0d6TFBzRVAwbUw5MGR1NExqbVNjWFRFb1ZqVk81b1dzejVaTC90ZllSOEpJTmRVTUJZM0g2UnNqeFFQZXdXLzYzUDVwdDN0eTZXUjl5dnN0RGpoMHliR01vZVVSZnZLTmtTTy9KaDBNQVpnRmcxRXozS0huZHJiRi9UeDBvZXJBZmNxYXdZVGZyMUtQN2ozR3FBRm5Tam1DNFhUTUFSVnJSNXdYUklCYzZFYXBEOE43blhiTXlDem03R2ZxNGFqWk5ocGl3djBkU1N2OE9KNkRwWG40WTQ2Y0toeUlPYXZraE5qcGdxZGV2SnI4ekZIZ0UxWENZODBVMUNoWTd4dGhqNWNqdVFYYVdkbVFDbXJKdCtkQlYxMXg1T3UyNngrNWNYSk9GL1lPV21QQkpSeWhVWUxhTXhaL05jTERXUVBEQTgvRTJzTWRjSlFaQzdtMWhZWDhvZG93dmhTOTJBWmJMUzFHRDZXd1BmZTYiLCJzaWduYXR1cmUiOiJNSUFHQ1NxR1NJYjNEUUVIQXFDQU1JQUNBUUV4RFRBTEJnbGdoa2dCWlFNRUFnRXdnQVlKS29aSWh2Y05BUWNCQUFDZ2dEQ0NBK013Z2dPSW9BTUNBUUlDQ0V3d1FVbFJuVlEyTUFvR0NDcUdTTTQ5QkFNQ01Ib3hMakFzQmdOVkJBTU1KVUZ3Y0d4bElFRndjR3hwWTJGMGFXOXVJRWx1ZEdWbmNtRjBhVzl1SUVOQklDMGdSek14SmpBa0JnTlZCQXNNSFVGd2NHeGxJRU5sY25ScFptbGpZWFJwYjI0Z1FYVjBhRzl5YVhSNU1STXdFUVlEVlFRS0RBcEJjSEJzWlNCSmJtTXVNUXN3Q1FZRFZRUUdFd0pWVXpBZUZ3MHhPVEExTVRnd01UTXlOVGRhRncweU5EQTFNVFl3TVRNeU5UZGFNRjh4SlRBakJnTlZCQU1NSEdWall5MXpiWEF0WW5KdmEyVnlMWE5wWjI1ZlZVTTBMVkJTVDBReEZEQVNCZ05WQkFzybFBVeUJUZVhOMFpXMXpNUk13RVFZRFZRUUtEQXBCY0hCc1pTQkpibU11TVFzd0NRWURWUVFHRXdKVlV6QlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJNSVZkKzNyMXNleUlZOW8zWENRb1NHTng3QzlieXdvUFlSZ2xkbEs5S1ZCRzROQ0R0Z1I4MEIrZ3pNZkhGVEQ5K3N5SU5hNjFkVHY5SktKaVQ1OER4T2pnZ0lSTUlJQ0RUQU1CZ05WSFJNQkFmOEVBakFBTUI4R0ExVWRJd1FZTUJhQUZDUHlTY1JQaytUdkorYkU5aWhzUDZLNy9TNUxNRVVHQ0NzR0FRVUZCd0VCQkRrd056QTFCZ2dyQmdFRkJRY3dBWVlwYUhSMGNEb3ZMMjlqYzNBdVlYQndiR1V1WTI5dEwyOWpjM0F3TkMxaGNIQnNaV0ZwWTJFek1ESXdnZ0VkQmdOVkhTQUVnZ0VVTUlJQkVEQ0NBUXdHQ1NxR1NJYjNZMlFGQVRDQi9qQ0J3d1lJS3dZQkJRVUhBZ0l3Z2JZTWdiTlNaV3hwWVc1alpTQnZiaUIwYUdseklHTmxjblJwWm1sallYUmxJR0o1SUdGdWVTQndZWEowZVNCaGMzTjFiV1Z6SUdGalkyVndkR0Z1WTJVZ2IyWWdkR2hsSUhSb1pXNGdZWEJ3YkdsallXSnNaU0J6ZEdGdVpHRnlaQ0IwWlhKdGN5QmhibVFnWTI5dVpHbDBhVzl1Y3lCdlppQjFjMlVzSUdObGNuUnBabWxqWVhSbElIQnZiR2xqZVNCaGJtUWdZMlZ5ZEdsbWFXTmhkR2x2YmlCd2NtRmpkR2xqWlNCemRHRjBaVzFsYm5SekxqQTJCZ2dyQmdFRkJRY0NBUllxYUhSMGNEb3ZMM2QzZHk1aGNIQnNaUzVqYjIwdlkyVnlkR2xtYVdOaGRHVmhkWFJvYjNKcGRIa3ZNRFFHQTFVZEh3UXRNQ3N3S2FBbm9DV0dJMmgwZEhBNkx5OWpjbXd1WVhCd2JHVXVZMjl0TDJGd2NHeGxZV2xqWVRNdVkzSnNNQjBHQTFVZERnUVdCQlNVVjl0djFYU0Job21KZGk5K1Y0VUg1NXRZSkRBT0JnTlZIUThCQWY4RUJBTUNCNEF3RHdZSktvWklodmRqWkFZZEJBSUZBREFLQmdncWhrak9QWdOSkFEQkdBaUVBdmdsWEgrY2VIbk5iVmVXdnJMVEhMK3RFWHpBWVVpTEhKUkFDdGg2OWIxVUNJUURSaXpVS1hkYmRickYwWURXeEhyTE9oOCtqNXE5c3ZZT0FpUTNJTE4ycVl6Q0NBdTR3Z2dKMW9BTUNBUUlDQ0VsdEw3ODZtTnFYTUFvR0NDcUdTTTQ5QkFNQ01HY3hHekFaQmdOVkJBTU1Fa0Z3Y0d4bElGSnZiM1FnUTBFZ0xTQkhNekVtTUNRR0ExVUVDd3dkUVhCd2JHVWdRMlZ5ZEdsbWFXTmhkR2x2YmlCQmRYUm9iM0pwZEhreEV6QVJCZ05WQkFvTUNrRndjR3hsSUVsdVl5NHhDekFKQmdOVkJBWVRBbFZUTUI0WERURTBNRFV3TmpJek5EWXpNRm9YRFRJNU1EVXdOakl6TkRZek1Gb3dlakV1TUN3R0ExVUVBd3dsUVhCd2JHVWdRWEJ3YkdsallYUnBiMjRnU1c1MFpXZHlZWFJwYjI0Z1EwRWdMU0JITXpFbU1DUUdBMVVFQ3d3ZFFYQndiR1VnUTJWeWRHbG1hV05oZEdsdmJpQkJkWFJvYjNKcGRIa3hFekFSQmdOVkJBb01Da0Z3Y0d4bElFbHVZeTR4Q3pBSkJnTlZCQVlUQWxWVE1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRThCY1JoQm5YWklYVkdsNGxnUWQyNklDaTc5NTdyazNnamZ4TGsrRXpWdFZtV3pXdUl0Q1hkZzBpVG51NkNQMTJGODZJeTNhN1puQyt5T2dwaFA5VVJhT0I5ekNCOURCR0JnZ3JCZ0VGQlFjQkFRUTZNRGd3TmdZSUt3WUJCUVVITUFHR0ttaDBkSEE2THk5dlkzTndMbUZ3Y0d4bExtTnZiUzl2WTNOd01EUXRZWEJ3YkdWeWIyOTBZMkZuTXpBZEJnTlZIUTRFRmdRVUkvSkp4RStUNU84bjVzVDJLR3cvb3J2OUxrc3dEd1lEVlIwVEFRSC9CQVV3QXdFQi96QWZCZ05WSFNNRUdEQVdnQlM3c042aFdET0ltcVNLbWQ2K3ZldXYyc3NrcXpBM0JnTlZIUjhFTURBdU1DeWdLcUFvaGlab2RIUndPaTh2WTNKc0xtRndjR3hsTG1OdmJTOWhjSEJzWlhKdmIzUmpZV2N6TG1OeWJEQU9CZ05WSFE4QkFmOEVCQU1DQVFZd0VBWUtLb1pJaHZkalpBWUNEZ1FDQlFBd0NnWUlLb1pJemowRUF3SURad0F3WkFJd09zOXlnMUVXbWJHRyt6WERWc3Bpdi9RWDdka1BkVTJpanI3eG5JRmVRcmVKK0pqM20xbWZtTlZCRFkrZDZjTCtBakF5TGRWRUliQ2pCWGRzWGZNNE81Qm4vUmQ4TENGdGxrL0djbW1DRW05VStIcDlHNW5MbXdtSklXRUdtUThKa2gwQUFER0NBWWN3Z2dHREFnRUJNSUdHTUhveExqQXNCZ05WQkFNTUpVRndjR3hsSUVGd2NHeHBZMkYwYVc5dUlFbHVkR1ZuY21GMGFXOXVJRU5CSUMwZ1J6TXhKakFrQmdOVkJBc01IVUZ3Y0d4bElFTmxjblJwWm1sallYUnBiMjRnUVhWMGFHOXlhWFI1TVJNd0VRWURWUVFLREFwQmNIQnNaU0JKYm1NdU1Rc3dDUVlEVlFRR0V3SlZVd0lJVERCQlNWR2RWRFl3Q3dZSllJWklBV1VEQkFJQm9JR1RNQmdHQ1NxR1NJYjNEUUVKQXpFTEJna3Foa2lHOXcwQkJ3RXdIQVlKS29aSWh2Y05BUWtGTVE4WERUSXpNREV6TURFME16RXhORm93S0FZSktvWklodmNOQVFrME1Sc3dHVEFMQmdsZ2hrZ0JaUU1FQWdHaENnWUlLb1pJemowRUF3SXdMd1lKS29aSWh2Y05BUWtFTVNJRUlJUGpmOU9aMFRwQjlhNmtId3I4YXRtdXN6MXF4Nk5KS0RrTDhVRWp3cmJoTUFvR0NDcUdTTTQ5QkFNQ0JFWXdSQUlnZjZLZmExNytEeW8zZlY0c1Y3Z1hpRDV1S25ieWdRSVUzd0M5QWQ1azF0WUNJQThwQ3FZakxBNzhaNkhuWkhSVW9HSWJrcDBOb1IyMTlCNXRuY3FmcDlFL0FBQUFBQUFBIiwiaGVhZGVyIjp7ImVwaGVtZXJhbFB1YmxpY0tleSI6Ik1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRVVWdStobVpaT1lOUTgxbGEySm1saWhPbnFmMEU3VWZOOENmM2ZobEp6Sy9TSzJoWDlIZGVwVDZoMjZBczJGSW5pQVhMN0c4elNjQW1LQVg2Q1ZTRmRnPT0iLCJhcHBsaWNhdGlvbkRhdGEiOiJlM2IwYzQ0Mjk4ZmMxYzE0OWFmYmY0Yzg5OTZmYjkyNDI3YWU0MWU0NjQ5YjkzNGNhNDk1OTkxYjc4NTJiODU1IiwicHVibGljS2V5SGFzaCI6IiswSVBCODBLa2JwOUxnTlNTSkROemFMVkdIYXdXSEIyRG9HYjFJay8yTjg9IiwidHJhbnNhY3Rpb25JZCI6ImUxZDBiYWNmYTFkNjFkY2YyYTc1MzhkNmM1ZDFlNjE1YjdlMGU4ZTJmM2YzOWU5N2JiMzI3NGQ5MGRhMWFjYjIifX0=

The following authorize payment request is an example of making payment:

<?xml version="1.0" encoding="UTF-8"?>
<root>
<authorize-payment account="[integer]" client-id="[integer]" >
<transaction type-id="40" id="[CELLPOINT DIGITAL-TXNID]">
<card network="visa" type-id="15">
   <address country-id="200">
     <first-name>Harish</first-name>
     <last-name>Chandra</last-name>
     <street>1131 Meadow Creek Dr.</street>
     <postal-code>75086</postal-code>
     <city>Irving</city><state>KY</state>
     <contact-details>
     </contact-details>
   </address>
<amount currency-id="[integer]" country-id="[integer]">100</amount>
<token>[token]</token>
</card>
</transaction><client-info version="10.02" app-version="10.02" sdk-version="2.3.1" language="gb" platform="iOS/15.5"><device-id>087E575D-92BD-483A-B1AA-C4F9CDCA5674</device-id></client-info></authorize-payment></root>

The Authorize Request parameters are listed in the table below:

Parameter

Type

Mandatory

Description

Authorize-payment Parameters

account

Integer

No

The number for a sub-account with which a payment transaction is associated. The account ID is an integer greater than 100000 and account number is an integer smaller than 1000.

The payment transaction is associated with the default sub-account if merchants do not provide this parameter.

client-id

Integer

Yes

The unique ID of a merchant.

Transaction Parameters

id

Integer

Yes

The ID of the transaction.

type-id

Integer

Yes

A unique transaction identification number.

card network

Enum

No

A list to identify the card network from which the token was obtained. It takes one of the following values:

  • amex
  • dankort
  • dinersclub
  • jcb
  • maestro
  • mastercard
  • visa
  • visaelectron
  • discover

Card Parameters

currency-id

Integer

Yes

The country currency code of a currency.

country-id

Integer

Yes

The CellPoint Digital-specific country code, which is made available to merchants on request.

token

String

No

The base64 encoded cryptogram for a third-party wallet such as Apple Pay™.

hmac

String

No

The Message Authentication Code (MAC). It is calculated by creating a sha-512 hash comprising the following input fields in the listed order:

ParameterRequired
clientidYes
orderidYes
amountYes
countryYes
mobileConditional
mobile-countryConditional
emailConditional
deviceidConditional
saltYes

Note: CELLPOINT DIGITAL provides the salt value to merchants.

MAC calculation secures the information sent by the merchant to Velocity by applying the SHA-512 encryption algorithm on key parts of the information sent to protect against tampering. The “salt” is the merchant's shared secret string used to ensure that MAC is unique.

Address Parameters

country-id

Integer

Yes

The CellPoint Digital-specific country code, which is made available to merchants on request.

full-name

String

Yes

The full name of a customer.

street

String

Yes

The full address of a customer with street name and street number.

postal-code

String

Yes

The postal code of a customer.

city

String

Yes

The city in which a customer resides.

state

String

No

The state in which a customer resides. Customers enter this parameter only if their country of residence is divided onto states.

country-id

Integer

Yes

The CellPoint Digital-specific country code, which is made available to merchants on request.

Client Information Parameters

language

String

Yes

The language that Velocity uses as default when translating the payment pages.

Note: Velocity language codes are based upon the ISO- 639-1 standard.

Refer to https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for details.

version

String

Yes

The version of an API or application that sends the request.

platform

String

Yes

The platform from which the request is sent. For example, web, iOS, Android, B2B, and B2C.

mobile operator-id

Integer

Yes

The ID of a customer’s mobile network operator. CellPoint Digital recommends including this parameter in the request to ensure Velocity correctly interacts with the operator.

email

String

No

The email address of a customer. If a customer provides this parameter, the Email input field on the Send Email Receipt page is automatically populated with this value.

9.2 Authorize Response

The Velocity server sends the response informing if the transaction authorization was a success or a failure. The following example shows that a payment request was authorized successfully:

<?xml version="1.0" encoding="UTF-8"?>
<root>
<status code="2000">Payment authorized</status>
</root>

The Authorize Response parameters are listed in the table below.

Parameter

Type

Mandatory

Description

Status

String

Yes

Describes the status code.

Code

Integer

Yes

Status code for the authorizing processes.