Perform sale

Introduction

Perform sale is initiated through HTTPS POST request by using URLs and the parameters.
On this stage Connecting Party’s app sends cardholder, device, session data and other parameters straight to ConnPay to perform sale transaction.

A lot of criteria checks and filters may be applied, such as BIN, currency, country, blacklisted or not, etc. Depending on the integration, these settings may be customizable.

API URLs

Integration

Production

https://sandbox.connpay.com/paynet/dapi/v1/sale/{endpointId}/{invoiceId}

https://gate.connpay.com/paynet/dapi/v1/sale/{endpointId}/{invoiceId}

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

consumer.email

Сonsumer’s email address, if sent in original card mapping transaction and card reference is being used instead of cardholder data.

Necessity: Required
Type: String
Length: 3-128

session

Necessity: Required
Type: Object

session.accessToken

Access token key received in Optional consumer authentication.

Necessity: Required
Type: String
Length: 32-128

session.nonce

Value received in initiate sale response.

Necessity: Required
Type: String
Length: 32-128

session.signature

Value received in initiate sale response.

Necessity: Required
Type: String
Length: 32-128

sourceOfFunds

Necessity: Required
Type: Object

sourceOfFunds.card

Only one of these subtypes (card, reference) should be used.

Necessity: Required
Type: Object

sourceOfFunds.card.expiry

Necessity: Required
Type: Object

sourceOfFunds.card.expiry.month

Source Card expiration month.

Necessity: Required
Type: Integer
Length: 2

sourceOfFunds.card.expiry.year

Source Card expiration year.

Necessity: Required
Type: Integer
Length: 4

sourceOfFunds.card.holder

Necessity: Required
Type: Object

sourceOfFunds.card.holder.firstName

Cardholder’s first name.

Necessity: Required
Type: String
Length: 1-50

sourceOfFunds.card.holder.lastName

Cardholder’s last name.

Necessity: Required
Type: String
Length: 1-50

sourceOfFunds.card.holder.printedName

Cardholder’s printed name (first and last name together). May be used instead of firstName + lastName.

Necessity: Required
Type: String
Length: 1-50

sourceOfFunds.card.number

Source card number (PAN).

Necessity: Required
Type: String
Length: 9-19

sourceOfFunds.card.securityCode

Source card security code (CVV).

Necessity: Required
Type: String
Length: 3-4

sourceOfFunds.reference

only one of these subtypes (card, reference) should be used.

Necessity: Required
Type: Object

sourceOfFunds.reference.clientCardId

Source card reference identifier (on client side).

Necessity: Required
Type: String
Length: 1-128

sourceOfFunds.reference.securityCode

Source card security code (CVV).

Necessity: Required
Type: String
Length: 3-4

transaction

Necessity: Required
Type: Object

transaction.amountCentis

Transaction amount, 1.00 EUR = 100 centis.

Necessity: Required
Type: Integer

transaction.currency

Upper case letters (ISO 4217 alpha code).

Necessity: Required
Type: String
Length: 3

location

Necessity: Optional
Type: Object

location.lat

The latitude specified in the range of -90.0 through +90.0, both inclusive.

Necessity: Optional
Type: Double

location.lng

The longitude specified in the range -180.0 through +180.0, both inclusive.

Necessity: Optional
Type: Double

billing

Necessity: Optional
Type: Object

billing.address

Necessity: Optional
Type: Object

billing.address.city

City name.

Necessity: Optional
Type: String
Length: 1-100

billing.address.country

ISO alpha3 country code.

Necessity: Optional
Type: String
Length: 3

billing.address.postcodeZip

ZIP post code.

Necessity: Optional
Type: String
Length: 1-10

billing.address.state

State is used if present. For example, Los Angeles is in CA state.

Necessity: Optional
Type: String
Length: 2-3

billing.address.street

Street is used for district names and street names.

Necessity: Optional
Type: String
Length: 1-50

billing.address.street2

Street 2 is used for long addresses. Usually it contains apartment and building №.

Necessity: Optional
Type: String
Length: 1-50

billing.phone

Сonsumer’s contact phone number.

Necessity: Optional
Type: String
Length: 1-20

consumer.birthDay

Сonsumer’s birth day in “ddMMyyyy” format.

Necessity: Optional
Type: String
Length: 8

consumer.device.imei

Сonsumer’s device international mobile equipment identity.

Necessity: Optional
Type: String
Length: 14-16

consumer.ipAddresses

Сonsumer’s IP addresses.

Necessity: Optional
Type: List

consumer.ipAddresses[]

Сonsumer’s IP address.

Necessity: Optional
Type: String
Length: 7-15

order

Necessity: Optional
Type: Object

order.description

Brief transaction description. May be mandatory for certain Acquirer Banks.

Necessity: Optional
Type: String
Length: 128

order.siteUrl

URL of website associated with the transaction.

Necessity: Optional
Type: String
Length: 128

order.purpose

May be used for better transaction control or additional checks.

Necessity: Optional
Type: String
Length: 128

Success Response Parameters

Parameter Name

Description

Value

invoiceId

Sale transaction identifier.

Type: String

session

Type: Object

session.token

The session token of sale transaction.

Type: String

Fail Response Parameters

Parameter Name

Description

Value

error

Type: Object

error.cause

Cause of the error. Possible values: INVALID_REQUEST, INVALID_CONFIGURATION, INTERNAL_ERROR, PROCESSING_FAILED.

Type: Enum

error.code

The unique error code.

Type: String

error.message

Description of the error.

Type: String

invoiceId

Sale transaction identifier.

Type: String

Request Example

{
  "billing": {
    "address": {
      "city": "string",
      "country": "string",
      "postcodeZip": "string",
      "state": "string",
      "street": "string",
      "street2": "string"
    },
    "phone": "string"
  },
  "consumer": {
    "birthDay": "string",
    "device": {
      "imei": "string",
      "serialNumber": "string"
    },
    "email": "string",
    "ipAddresses": ["string"]
  },
  "location": {
    "lat": "double",
    "lng": "double"
  },
  "order": {
    "description": "string",
    "siteUrl": "string",
    "purpose": "string"
  },
  "session": {
    "accessToken": "string",
    "nonce": "string",
    "signature": "string"
  },
  "sourceOfFunds": {
    "card": {
      "expiry": {
        "month": "integer",
        "year": "integer"
      },
      "holder":{
        "firstName": "string",
        "lastName": "string"
      },
      "number": "string",
      "securityCode": "string"
    },
    "reference": {
      "clientCardId": "string",
      "securityCode": "string"
    }
  },
  "transaction": {
    "amountCentis": "integer",
    "currency": "string"
  }
}

Success Response Example

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

Fail Response Example

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

Request Builder

For integration purposes use ConnPay test scenarios to generate random card numbers.

Endpoint Id
Invoice Id

Generated by Merchant's server in "Initiate sale"

Device serial number
Device imei
E-mail
Birthday
Ip Address
accessToken

Generated by Merchant's server in "Consumer authentication"

nonce

Generated by Merchant's server in "Initiate sale"

signature

Generated by Merchant's server in "Initiate sale"

Source Card number

Use either card number or clientCardId, not both

CVV for a new card

Leave empty if clientCardId is being used

Card expiry month

Leave empty if clientCardId is being used

Card expiry year

Leave empty if clientCardId is being used

First name

Leave empty if clientCardId is being used

Last name

Leave empty if clientCardId is being used

Source Card reference

Use either card number or clientCardId, not both

CVV for the reference

Leave empty if new card is being used

Sale amount

Will be calculated to centis in generated string

Currency

ISO 4217 alpha three-letter code

Loc. Latitude
Loc. Longitude
City
Country
ZIP Postcode
State
Street
Street2
Phone
Order description
Order site Url