Perform a payment gateway authorize operation

curl --request POST \
  --url https://api.orchestrasolutions.com/PaymentGateway/authorize \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "currency": "<string>",
  "amount": 123,
  "card": {
    "cardHolderName": "<string>",
    "cardNumber": "<string>",
    "expirationYear": 123,
    "expirationMonth": 123,
    "ownerID": "<string>",
    "issueNumber": "<string>",
    "cvv": "<string>",
    "threeDSAuthentication": {
      "authenticationValue": "<string>",
      "eci": "<string>",
      "xid": "<string>",
      "version": "<string>",
      "merchantName": "<string>",
      "sli": "<string>"
    },
    "cardType": "Unspecified"
  },
  "isDigital": true,
  "orderDesc": "<string>",
  "userToken": "<string>",
  "generateToken": true,
  "payerDetails": {
    "clientIPAddress": "<string>",
    "countryCode": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "address3": "<string>",
    "postCode": "<string>",
    "city": "<string>",
    "stateProvince": "<string>"
  },
  "myRef": "<string>",
  "paymentGatewayAccountName": "<string>",
  "certificateName": "<string>",
  "paymentGatewayAccount": {
    "paymentGatewayName": "<string>",
    "credentials": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ]
  },
  "networkTokenBrand": "Visa"
}
'

{
  "authorizationCode": "<string>",
  "currency": "AFN",
  "amount": 123,
  "operationType": "Charge",
  "operationResultCode": "Success",
  "operationResultDescription": "<string>",
  "customGatewayResponse": "<unknown>",
  "gatewayName": "<string>",
  "gatewayReference": "<string>",
  "gatewayResultCode": "<string>",
  "gatewayResultDescription": "<string>",
  "gatewayResultSubCode": "<string>",
  "gatewayResultSubDescription": "<string>",
  "gatewayToken": "<unknown>"
}

Payment Operations

Perform a payment gateway authorize operation

This method allows you to perform an “authorize” operation (also called “preauthorization” or “authorization”) through your payment gateway. When you perform the “authorize” operation, the bank that issued the credit card will place an authorization of the total amount of the funds. This is how the bank determines if the funds are available to make the purchase. The card will not actually be “charged” until you perform the “capture” operation (using our [PUT] /PaymentGateway/capture method). Please note, different card brands and different banks allow for different time frames on the lifespan of a payment authorization. You will need to check with your payment processor on how long you would have between performing an “authorize” operation and a “charge” operation”. If needed, you can void this “authorize” operation by using the [DELETE] /PaymentGateway/void method

POST

PaymentGateway

authorize

curl --request POST \
  --url https://api.orchestrasolutions.com/PaymentGateway/authorize \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "currency": "<string>",
  "amount": 123,
  "card": {
    "cardHolderName": "<string>",
    "cardNumber": "<string>",
    "expirationYear": 123,
    "expirationMonth": 123,
    "ownerID": "<string>",
    "issueNumber": "<string>",
    "cvv": "<string>",
    "threeDSAuthentication": {
      "authenticationValue": "<string>",
      "eci": "<string>",
      "xid": "<string>",
      "version": "<string>",
      "merchantName": "<string>",
      "sli": "<string>"
    },
    "cardType": "Unspecified"
  },
  "isDigital": true,
  "orderDesc": "<string>",
  "userToken": "<string>",
  "generateToken": true,
  "payerDetails": {
    "clientIPAddress": "<string>",
    "countryCode": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "address3": "<string>",
    "postCode": "<string>",
    "city": "<string>",
    "stateProvince": "<string>"
  },
  "myRef": "<string>",
  "paymentGatewayAccountName": "<string>",
  "certificateName": "<string>",
  "paymentGatewayAccount": {
    "paymentGatewayName": "<string>",
    "credentials": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ]
  },
  "networkTokenBrand": "Visa"
}
'

{
  "authorizationCode": "<string>",
  "currency": "AFN",
  "amount": 123,
  "operationType": "Charge",
  "operationResultCode": "Success",
  "operationResultDescription": "<string>",
  "customGatewayResponse": "<unknown>",
  "gatewayName": "<string>",
  "gatewayReference": "<string>",
  "gatewayResultCode": "<string>",
  "gatewayResultDescription": "<string>",
  "gatewayResultSubCode": "<string>",
  "gatewayResultSubDescription": "<string>",
  "gatewayToken": "<unknown>"
}

This method allows you to perform an “authorize” operation (also called “preauthorization” or “authorization”) through your payment gateway. When you perform the “authorize” operation, the bank that issued the credit card will place an authorization of the total amount of the funds. This is how the bank determines if the funds are available to make the purchase. The card will not actually be “charged” until you perform the “capture” operation (using the PUT /PaymentGateway/capture method). Please note: Different card brands and different banks allow for different time frames on the lifespan of a payment authorization. Check with your payment processor on how long you have between performing an “authorize” operation and a “capture” operation. If needed, you can void this “authorize” operation using the DELETE /PaymentGateway/void method.

Additional parameters may be requiredSome payment processors require custom parameters and properties to be added to the request. See Gateway-Specific Requirements for processors that require additional information.

Payment gateway merchant account credentialsOrchestra offers two options for providing merchant account credentials:

Inline credentials: Provide the merchant account credentials in the request using the paymentGatewayAccount object.
Stored credentials: Use our Payment Gateway Accounts system to pre-upload and store credentials, then reference them with the paymentGatewayAccountName parameter.

Authorize & Capture Guide

Complete guide with examples, capture flow, and best practices

Authorizations

X-Api-Key

string

header

required

Please enter ApiKey into field

Body

application/json

Card Authorize model

currency

string

required

The currency of the transaction. Based on the ISO 4217 standard.

Minimum string length: 1

amount

number<double>

required

The amount to be charged (the amount should be in major units - for example, 10.23)

card

object

required

The card details that should be charged. You can either provide us with the raw card details or provide a reference to the stored card details in a token.

Show child attributes

isDigital

boolean

This field is an additional optional parameter used by some of our payment processors. Please read our additional guidance section for payment processors that use this and other parameters

orderDesc

string | null

This field is an additional optional parameter used by some of our payment processors. Please read our additional guidance section for payment processors that use this and other parameters

userToken

string | null

Token from gateway to be used instead of card details

generateToken

boolean

Whether to generate a payment gateway token

payerDetails

object

The billing information of the card owner

Show child attributes

myRef

string | null

Your custom reference for this transaction

paymentGatewayAccountName

string | null

The reference name provided to the stored Payment Gateway Account as set in PUT /PaymentGatewayAccounts/{name}. Please note, if you provide us with both this parameter and the raw credentials in the paymentGatewayAccount object, this parameter will be ignored and the raw credentials will take precedence.

certificateName

string | null

Optional parameter if the payment gateway requires authentication using a client certificate. The name of the certificate that was stored in our system via our users portal

Maximum string length: 128

paymentGatewayAccount

object

The raw credentials necessary to connect to the chosen payment gateway as defined in GET /PaymentGateway. Please note, if you provide us with both the raw details here and a stored Payment Gateway Account in the paymentGatewayAccountName parameter, these credentials will take precedence.

Show child attributes

networkTokenBrand

enum<string>

Available options:

Visa,

MasterCard,

Amex

Response

authorizationCode

string | null

currency

enum<string>

Available options:

AFN,

EUR,

ALL,

DZD,

USD,

AOA,

XCD,

ARS,

AMD,

AWG,

AUD,

AZN,

BSD,

BHD,

BDT,

BBD,

BYR,

BZD,

XOF,

BMD,

BTN,

INR,

BOB,

BOV,

BAM,

BWP,

NOK,

BRL,

BND,

BGN,

BIF,

KHR,

XAF,

CAD,

CVE,

KYD,

CLF,

CLP,

CNY,

COP,

COU,

KMF,

CDF,

NZD,

CRC,

HRK,

CUC,

CUP,

ANG,

CZK,

DKK,

DJF,

DOP,

EGP,

SVC,

ERN,

ETB,

FKP,

FJD,

XPF,

GMD,

GEL,

GHS,

GIP,

GTQ,

GBP,

GNF,

GYD,

HTG,

HNL,

HKD,

HUF,

ISK,

IDR,

XDR,

IRR,

IQD,

ILS,

JMD,

JPY,

JOD,

KZT,

KES,

KPW,

KRW,

KWD,

KGS,

LAK,

LBP,

LSL,

ZAR,

LRD,

LYD,

CHF,

LTL,

MOP,

MKD,

MGA,

MWK,

MYR,

MVR,

MRO,

MUR,

XUA,

MXN,

MXV,

MDL,

MNT,

MAD,

MZN,

MMK,

NAD,

NPR,

NIO,

NGN,

OMR,

PKR,

PAB,

PGK,

PYG,

PEN,

PHP,

PLN,

QAR,

RON,

RUB,

RWF,

SHP,

WST,

STD,

SAR,

RSD,

SCR,

SLL,

SGD,

XSU,

SBD,

SOS,

SSP,

LKR,

SDG,

SRD,

SZL,

SEK,

CHE,

CHW,

SYP,

TWD,

TJS,

TZS,

THB,

TOP,

TTD,

TND,

TRY,

TMT,

UGX,

UAH,

AED,

USN,

UYI,

UYU,

UZS,

VUV,

VEF,

VND,

YER,

ZMW,

ZWL,

XBA,

XBB,

XBC,

XBD,

XTS,

XXX,

XAU,

XPD,

XPT,

XAG

amount

number<double>

operationType

enum<string>

Available options:

Charge,

PreAuth,

Capture,

Void,

Refund,

Tokenize,

Status

operationResultCode

enum<string>

Available options:

Success,

Accepted,

Rejected,

TemporaryFailure,

FatalFailure,

NotImplemented

operationResultDescription

string | null

customGatewayResponse

unknown

gatewayName

string | null

gatewayReference

string | null

gatewayResultCode

string | null

gatewayResultDescription

string | null

gatewayResultSubCode

string | null

gatewayResultSubDescription

string | null

gatewayToken

unknown

Perform a payment gateway charge operation Perform a payment gateway capture operation

⌘I

Overview

Payment Operations

String Tokens

Payment Gateway Accounts

Utilities

Payments Library (Internal)

Perform a payment gateway authorize operation

Authorize & Capture Guide

Authorizations

Body

Response