createAuthorization

MUTATION

Creates an authorization for a merchant. With a non-empty idempotency_key, retrying the same request returns the original authorization, including a failed result. Reusing the key with changed request details returns a conflict. Concurrent requests with the same key create one authorization.

Arguments

merchant_uidRequired

String

The Pay Theory unique identifier assigned to the merchant that the authorization belongs to.

idempotency_key

String

Optional caller-provided key for identifying retries of this authorization request.

sale_id

String

The Pay Theory unique identifier assigned to the sale that the authorization belongs to. Sales can be used to tie together multiple auths and captures.

amountRequired

Int

The amount of the authorization in cents.

payment_method_id

String

The Pay Theory unique identifier assigned to the payment method that will be used for the authorization.

payment_method

PaymentMethodInput

The payment method input object for the payment method that will be used for the authorization. More information on the payment method input object can be found here.

invoice_id

String

The Pay Theory unique identifier assigned to the invoice that the authorization belongs to.

fee

Int

The amount of the service fee in cents.

fee_mode

FeeMode

The fee mode for the authorization. It can be one of the following: SERVICE_FEE, MERCHANT_FEE

Values

CUSTOM_FEEINTERCHANGEMERCHANT_FEESERVICE_FEE

account_code

String

Custom defined value passed in as the account code for the authorization.

reference

String

Custom defined value passed in as the reference for the authorization.

metadata

AWSJSON

Any additional data that should be stored with the authorization.

health_expense_type

HealthExpenseType

The health expense type for the authorization. It can be one of the following: CLINICAL, COPAY, DENTAL, HEALTHCARE, RX, TRANSIT, VISION

Values

CLINICALCOPAYDENTALHEALTHCARERXTRANSITVISION

digital_wallet

DigitalWalletInput

-

additional_purchase_data

AdditionalPurchaseDataInput

Additional purchase data for Level 3 processing requirements.

one_time_use_token

Boolean

If the payment method token should be used for a single transaction. Defaults to false. If set to true the is_active flag on the payment method will be set to false after the authorization.

Response

Authorization

account_code

String| null

Custom defined value passed in as the account code for the authorization.

additional_purchase_data

AdditionalPurchaseData| null

Additional purchase data for Level 3 processing requirements.

amount

Int

The amount of the authorization in cents.

authorization_date

AWSDateTime

The date and time the authorization was created.

authorization_id

String

The Pay Theory unique identifier assigned to the authorization.

avs_status

AvsStatus| null

The AVS status of the authorization.

Values

NO_MATCHPOSTAL_CODE_AND_STREET_MATCHPOSTAL_CODE_MATCHSTREET_MATCHUNKNOWN

captured_amount

Int| null

The amount of the authorization that has been captured in cents.

currency

String

The currency of the authorization. Currently only USD is supported.

device_id

String| null

-

expiration_date

AWSDateTime| null

The date and time the authorization will expire.

failure_reasons

[String]| null

Array of failure reasons for the authorization. If the authorization is successful, this will be null.

fee_mode

FeeMode

The fee mode for the authorization. It can be one of the following: SERVICE_FEE, MERCHANT_FEE

Values

CUSTOM_FEEINTERCHANGEMERCHANT_FEESERVICE_FEE

fees

Int

The amount of fees for the authorization in cents.

invoice

Invoice| null

The invoice object for the invoice that the authorization belongs to. More information on the invoice object can be found here.

merchant_uid

String

The Pay Theory unique identifier assigned to the merchant to batch for.

metadata

AWSJSON| null

Any additional data that was stored with the authorization.

payment_method

PaymentMethodToken

The payment method token object for the payment method that the authorization belongs to. More information on the payment method token object can be found here.

processor

String| null

-

reference

String| null

Custom defined value passed in as the reference for the authorization.

sale_id

String| null

The Pay Theory unique identifier assigned to the sale that the authorization belongs to. Sales can be used to tie together multiple auths and captures.

status

AuthorizationStatus

The status of the authorization. It can be one of the following: CANCELLED, FAILED, SUCCEEDED

Values

CANCELEDFAILEDSUCCEEDED

timezone

String| null

The timezone of the authorization.

transaction_id

String| null

The Pay Theory unique identifier assigned to the transaction that the authorization belongs to.

updated_row_at

AWSDateTime| null

The date and time the authorization was last updated.

Examples

Create an authorization with an idempotency key

Places a hold on a card. Use a new key for each new authorization, and reuse it only to retry this request.

SUCCESS 200

GRAPHQL

mutation CreateAuthorization(
  $merchant_uid: String!
  $amount: Int!
  $idempotency_key: String
  $payment_method: PaymentMethodInput
  $fee_mode: FeeMode
) {
  createAuthorization(
    merchant_uid: $merchant_uid
    amount: $amount
    idempotency_key: $idempotency_key
    payment_method: $payment_method
    fee_mode: $fee_mode
  ) {
    authorization_id
    merchant_uid
    amount
    currency
    status
    fee_mode
    fees
    authorization_date
    expiration_date
    sale_id
  }
}