--- title: "Authorize a closed loop transaction" method: POST path: "/programs/{programCode}/payments/authorize" tags: ["Payment"] --- # Authorize a closed loop transaction `POST /programs/{programCode}/payments/authorize` Authorizes a closed loop transaction for the specified payment instrument and amount. ## Path parameters - `programCode` string, required ## Headers - `X-GD-RequestId` string, required ## Request body - AuthorizePaymentRequest — Represents a request to authorize a payment transaction. Contains transaction, card, merchant, and terminal details for payment authorization. Inherits standard request metadata from Gd.Bos.DataTransfer.Request.RequestBase. - `messageType` string, nullable — The type of message for the payment authorization (e.g., "Authorization", "Advice"). - `paymentInstrumentIdentifier` string, nullable — The identifier of the payment instrument used for the transaction (e.g., card or account number). - `encryptedCardData` EncryptedData — Represents a container for encrypted data used in secure data transfer operations. Contains the encrypted payload and associated cryptographic metadata, including encryption version, ephemeral public key, and public key hash. Used to securely transmit sensitive information such as user data, ensuring confidentiality and integrity during transport. - `version` string, nullable — The version of the encryption algorithm used to encrypt the data (e.g., "v1", "v2"). - `ephemeralPublicKey` string, nullable — The ephemeral public key used in the encryption process, typically for key exchange or session establishment. - `publicKeyHash` string, nullable — The hash of the public key used to verify the integrity and authenticity of the encryption key. - `data` string, nullable — The encrypted data payload, typically base64-encoded, containing the sensitive information. - `transactionIdentifier` string, nullable — The unique identifier for the payment transaction. - `systemTraceNumber` string, nullable — The system trace number for the transaction, used for tracking and reconciliation. - `transactionCode` string, nullable — The transaction code indicating the type of transaction (e.g., purchase, refund). - `accountType` string, nullable — The type of account involved in the transaction (e.g., "Checking", "Savings", "Credit"). - `posEntryMode` PosEntryMode — Represents the point-of-sale entry mode details for a payment transaction. Contains card input, authentication, and terminal capability information. - `cardInputCapability` string, nullable — The card input capability of the terminal (e.g., "Chip", "Magstripe", "Contactless"). - `cardholderAuthenticationCapability` string, nullable — The cardholder authentication capability of the terminal. - `cardCaptureCapability` string, nullable — The card capture capability of the terminal. - `operatingEnvironment` string, nullable — The operating environment of the terminal (e.g., "Attended", "Unattended"). - `cardholderPresence` string, nullable — Indicates whether the cardholder is present at the terminal. - `cardPresence` string, nullable — Indicates whether the card is present at the terminal. - `cardDataInputMode` string, nullable — The card data input mode (e.g., "Manual", "Swipe", "Chip"). - `cardholderAuthenticationMethod` string, nullable — The cardholder authentication method used (e.g., "PIN", "Signature"). - `cardholderAuthenticationEntity` string, nullable — The entity responsible for cardholder authentication. - `cardDataOutputCapability` string, nullable — The card data output capability of the terminal. - `terminalOutputCapability` string, nullable — The terminal output capability (e.g., "Display", "Print"). - `pinCaptureCapability` string, nullable — The PIN capture capability of the terminal. - `transactionAmount` number, double, nullable — The authorized transaction amount. - `transactionCurrency` string, nullable — The currency code for the transaction (e.g., "USD", "EUR"). - `transactionFeeAmount` number, double, nullable — The transaction fee amount, if applicable. - `transmissionDateTime` string, nullable — The transmission date and time of the transaction, formatted as a string. - `localDateTime` string, nullable — The local date and time of the transaction, formatted as a string. - `settlementDateTime` string, nullable — The settlement date and time for the transaction, formatted as a string. - `acquiringCountryCode` string, nullable — The acquiring country code for the transaction. - `cardSequenceNumber` string, nullable — The card sequence number, used for multi-card accounts. - `functionCode` string, nullable — The function code for the transaction, indicating specific processing logic. - `messageReasonCode` integer, nullable — The message reason code, used for specific transaction scenarios. - `merchant` Merchant — Represents merchant details for a payment transaction. Contains merchant identification, industry, and address information. - `merchantId` string, nullable — The unique identifier for the merchant. - `merchantName` string, nullable — The name of the merchant. - `merchantIndustryCode` string, nullable — The industry code for the merchant (e.g., "5411" for grocery stores). - `merchantIndustryCategory` string, nullable — The industry category for the merchant. - `merchantIndustryDescription` string, nullable — The industry description for the merchant. - `addressLine1` string, nullable — The first line of the merchant's address. - `city` string, nullable — The city where the merchant is located. - `postalCode` string, nullable — The postal code for the merchant's address. - `stateProvReg` string, nullable — The state, province, or region for the merchant's address. - `country` string, nullable — The country where the merchant is located. - `originalAmount` number, double, nullable — The original transaction amount, used for reversals or adjustments. - `acquirerId` string, nullable — The acquirer identifier for the transaction. - `retrievalReferenceNumber` string, nullable — The retrieval reference number for the transaction, used for audit and dispute purposes. - `terminalIdentifier` string, nullable — The terminal identifier where the transaction was processed. - `originalTransactionForReversal` OriginalTransactionForReversal — Represents the original transaction details for a reversal operation. Contains identifiers and timestamps for the original transaction. - `messageType` string, nullable — The type of message for the original transaction. - `systemTraceNumber` string, nullable — The system trace number for the original transaction. - `localDateTime` string, nullable — The local date and time of the original transaction. - `acquirerId` string, nullable — The acquirer identifier for the original transaction. - `eCommerceIndicator` string, nullable — The e-commerce indicator for the transaction, specifying online or card-not-present status. ## Response `200` OK - AuthorizePaymentResponse — Represents the response returned after authorizing a payment transaction. Contains transaction identifiers, amounts, approval codes, and related metadata. Inherits standard response metadata from Gd.Bos.DataTransfer.Response.ResponseBase. - `messageType` string, nullable — The type of message returned for the payment authorization (e.g., "Authorization", "Advice"). - `paymentInstrumentIdentifier` string, nullable — The identifier of the payment instrument used for the transaction (e.g., card or account number). - `transactionIdentifier` string, nullable — The unique identifier for the payment transaction. - `systemTraceNumber` string, nullable — The system trace number for the transaction, used for tracking and reconciliation. - `retrievalReferenceNumber` string, nullable — The retrieval reference number for the transaction, used for audit and dispute purposes. - `transactionAmount` number, double, nullable — The authorized transaction amount. - `transactionCurrency` string, nullable — The currency code for the transaction (e.g., "USD", "EUR"). - `approvalCode` string, nullable — The approval code returned by the payment network or processor. - `actionCode` string, nullable — The action code indicating the result of the authorization (e.g., "00" for approved, "05" for declined). - `additionalAmount` number, double, nullable — Any additional amount authorized or related to the transaction (e.g., cashback). - `responseDetails` ResponseDetail[], nullable — Required: A list of response details providing status codes, descriptions, and additional information about the result of the operation. - `code` integer — The primary status or error code for the response (e.g., 200 for success, 400 for validation error). - `subCode` integer, nullable — An optional subcode providing more granular detail about the response or error. - `description` string, nullable — A human-readable description of the response, error, or status. - `url` string, nullable — A URL linking to documentation or a web page with more information about the response code. ## Other responses - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error - `503` — Service Unavailable --- [API](https://skmtc.net/greendot/apis/baas-apis.md) · [All operations](https://skmtc.net/greendot/apis/baas-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/greendot/baas-apis/revisions/666553766b78/schema)