Aera PSP API documentation
This page contains API docs for the real Aera PSP.
Please note that this page is only temporary. It will be moved to a separate Aera PSP space in readme once it is ready.
See API reference for a more human readable version: Aera PSP
Aera PSP API doc (swagger)
WLW payment APIs using the Aera PSP.
{
"openapi" : "3.0.1",
"info" : {
"title" : "Unified Commerce Services",
"description" : "Aera Payment & Identification Unified Commerce Platform",
"version" : "v1.0.0"
},
"externalDocs" : {
"description" : "Aera Payment & Identification Unified Commerce Platform Documentation",
"url" : "https://api-docs.aerahost.com/"
},
"servers" : [
{
"url" : "https://psp.aerahost.com/uc",
"description" : "Generated server url"
}
],
"tags" : [
{
"name" : "ecomHealth",
"description" : "API for eCom Services Health"
}
],
"paths" : {
"/v1/wallet/sale" : {
"post" : {
"tags" : [
"unified"
],
"summary" : "Wallet sale - Initiates an asynchronous wallet payment.",
"operationId" : "walletSale",
"parameters" : [
{
"name" : "Accept",
"in" : "header",
"description" : "The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Authorization",
"in" : "header",
"description" : "The Bearer Access Token needed to get authorized to use the API.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "x-api-key",
"in" : "header",
"description" : "The x-api-key header needed to get access to the API services.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Content-Type",
"in" : "header",
"description" : "The content type of the body.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "idempotency-key",
"in" : "header",
"description" : "The Idempotency-Key header needed to create idempotent requests. Must be on UUID format.",
"required" : true,
"schema" : {
"pattern" : "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$",
"type" : "string"
}
},
{
"name" : "merchant-id",
"in" : "header",
"description" : "Aera assigned merchantId",
"required" : true,
"schema" : {
"pattern" : "^[a-zA-Z0-9\\-]{1,13}$",
"type" : "string"
}
}
],
"requestBody" : {
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentRequest"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Successful wallet sale initialization",
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
}
}
}
}
}
},
"/v1/wallet/sale/hybrid" : {
"post" : {
"tags" : [
"unified"
],
"summary" : "Wallet sale with item types - Initiates an asynchronous wallet payment with item types.",
"operationId" : "walletSaleItemTypes",
"parameters" : [
{
"name" : "Accept",
"in" : "header",
"description" : "The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Authorization",
"in" : "header",
"description" : "The Bearer Access Token needed to get authorized to use the API.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "x-api-key",
"in" : "header",
"description" : "The x-api-key header needed to get access to the API services.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Content-Type",
"in" : "header",
"description" : "The content type of the body.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "idempotency-key",
"in" : "header",
"description" : "The Idempotency-Key header needed to create idempotent requests. Must be on UUID format.",
"required" : true,
"schema" : {
"pattern" : "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$",
"type" : "string"
}
},
{
"name" : "merchant-id",
"in" : "header",
"description" : "Aera assigned merchantId",
"required" : true,
"schema" : {
"pattern" : "^[a-zA-Z0-9\\-]{1,13}$",
"type" : "string"
}
}
],
"requestBody" : {
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletHybridPaymentRequest"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletHybridPaymentRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "Successful wallet sale initialization",
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
}
}
}
}
}
},
"/v1/wallet/cancel/{referenceType}/{reference}" : {
"post" : {
"tags" : [
"unified"
],
"summary" : "Wallet cancel payment - Cancel a Wallet payment.",
"operationId" : "cancel",
"parameters" : [
{
"name" : "referenceType",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "reference",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Accept",
"in" : "header",
"description" : "The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Authorization",
"in" : "header",
"description" : "The Bearer Access Token needed to get authorized to use the API.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "x-api-key",
"in" : "header",
"description" : "The x-api-key header needed to get access to the API services.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Content-Type",
"in" : "header",
"description" : "The content type of the body.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "idempotency-key",
"in" : "header",
"description" : "The Idempotency-Key header needed to create idempotent requests. Must be on UUID format.",
"required" : true,
"schema" : {
"pattern" : "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$",
"type" : "string"
}
},
{
"name" : "merchant-id",
"in" : "header",
"description" : "Aera assigned merchantId",
"required" : true,
"schema" : {
"pattern" : "^[a-zA-Z0-9\\-]{1,13}$",
"type" : "string"
}
}
],
"responses" : {
"200" : {
"description" : "Successful wallet payment cancellation",
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletPaymentResponse"
}
}
}
}
}
}
},
"/v1/wallet/status/{referenceType}/{reference}" : {
"get" : {
"tags" : [
"unified"
],
"summary" : "Wallet status - Retrieves the status of a Wallet payment.",
"operationId" : "getStatus",
"parameters" : [
{
"name" : "referenceType",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "reference",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Accept",
"in" : "header",
"description" : "The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Authorization",
"in" : "header",
"description" : "The Bearer Access Token needed to get authorized to use the API.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "x-api-key",
"in" : "header",
"description" : "The x-api-key header needed to get access to the API services.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "merchant-id",
"in" : "header",
"description" : "Aera assigned merchantId",
"required" : true,
"schema" : {
"pattern" : "^[a-zA-Z0-9\\-]{1,13}$",
"type" : "string"
}
}
],
"responses" : {
"200" : {
"description" : "Successful wallet status",
"content" : {
"application/vnd.payments.v1+json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletStatusResponse"
}
},
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/WalletStatusResponse"
}
}
}
}
}
}
}
},
"components" : {
"schemas" : {
"ResponseInfo" : {
"required" : [
"responseCode",
"timeStamp"
],
"type" : "object",
"properties" : {
"message" : {
"type" : "string",
"description" : "Specific response message",
"example" : "Example message (often 'null' if responseCode=0)"
},
"responseCode" : {
"minLength" : 1,
"type" : "string",
"description" : "The response code from the system. Mandatory.",
"example" : "0"
},
"externalResponseCode" : {
"type" : "string",
"description" : "Additional response code from external systems.",
"example" : "0"
},
"cid" : {
"type" : "string",
"description" : "A Correlation ID (CID), which can eg. can be used in support cases.",
"example" : "Root=1-5759e988-bd862e3fe1be46a994272793"
},
"cidType" : {
"type" : "string",
"description" : "The type of Correlation ID (CID).",
"example" : "x-amzn-trace-id"
},
"timeStamp" : {
"type" : "string",
"description" : "Timestamp. Mandatory",
"example" : "2021-12-21T10:23:19.279Z"
}
},
"description" : "Info object that can provide specific messages"
},
"Attribute" : {
"required" : [
"key",
"value"
],
"type" : "object",
"properties" : {
"key" : {
"type" : "string"
},
"value" : {
"type" : "string"
}
}
},
"ProprietaryData" : {
"type" : "object",
"properties" : {
"attributes" : {
"maxItems" : 10,
"minItems" : 0,
"type" : "array",
"description" : "List of attribute key value",
"items" : {
"$ref" : "#/components/schemas/Attribute"
}
},
"salesDate" : {
"type" : "string",
"description" : "Sales date",
"format" : "date"
}
},
"description" : "Proprietary data"
},
"AmountDetailsWallet" : {
"required" : [
"amount",
"currency"
],
"type" : "object",
"properties" : {
"amount" : {
"type" : "integer",
"description" : "The amount to authorize in cents, including cashBackAmount",
"format" : "int64",
"example" : 1587
},
"cashBackAmount" : {
"type" : "integer",
"description" : "The amount used in cashBack in cents. Should be 'null' if no cashback amount.",
"format" : "int64"
},
"currency" : {
"type" : "string",
"description" : "The currency code (ISO 4217 alpha-3)",
"example" : "EUR"
}
},
"description" : "Payed amount in minor units"
},
"ClaimedUserIdentifier" : {
"required" : [
"cuid",
"cuidType"
],
"type" : "object",
"properties" : {
"cuid" : {
"maxLength" : 50,
"minLength" : 8,
"type" : "string",
"description" : "Claimed User ID. Typically an SDK ID or ideally a dynamic SDK ID.",
"example" : "3468dc992c"
},
"cuidType" : {
"type" : "string",
"description" : "The type Claimed User ID.",
"example" : "LOYALTY",
"enum" : [
"LOYALTY",
"SDKID",
"DYNAMIC_SDKID"
]
}
},
"description" : "Claimed User IDs. Typically an 'SDKID' (or ideally a 'DYNAMIC_SDKID') or some sort of additionalId/loyalty id ('LOYALTY')."
},
"WalletPaymentRequest" : {
"required" : [
"amountDetails",
"callbackUrl",
"claimedUserIds",
"dpaId",
"merchantReference"
],
"type" : "object",
"properties" : {
"callbackUrl" : {
"minLength" : 1,
"type" : "string",
"description" : "The URL to receive the callback after the asynchronous operation is completed or has timed out.",
"example" : "https://my-api.com"
},
"claimedUserIds" : {
"uniqueItems" : true,
"type" : "array",
"description" : "Claimed User IDs. Typically an 'SDKID' (or ideally a 'DYNAMIC_SDKID') or some sort of additionalId/loyalty id ('LOYALTY').",
"items" : {
"$ref" : "#/components/schemas/ClaimedUserIdentifier"
}
},
"dpaId" : {
"type" : "string",
"description" : "The Mobile Payment Application ID",
"format" : "uuid",
"example" : "2bf169ba-9dd9-4b06-88c0-122b8843954f"
},
"merchantReference" : {
"minLength" : 1,
"type" : "string",
"description" : "The merchant reference is used to link the customers specific order to the PSP transaction",
"example" : "2e6d1236-4b3a-435d-a86c-6a15449a73df"
},
"proprietaryData" : {
"$ref" : "#/components/schemas/ProprietaryData"
},
"amountDetails" : {
"$ref" : "#/components/schemas/AmountDetailsWallet"
}
}
},
"WalletPaymentResponse" : {
"type" : "object",
"properties" : {
"responseInfo" : {
"$ref" : "#/components/schemas/ResponseInfo"
},
"pspReference" : {
"type" : "string",
"description" : "The PSP reference to the payment",
"example" : "d66e7e45-3b91-44c8-a18c-67f65b6cd30d"
},
"merchantReference" : {
"type" : "string",
"description" : "The Merchant reference to the payment",
"example" : "26c352a8-837d-4386-9108-3fdbc20ce4bc"
}
}
},
"CategoryWallet" : {
"required" : [
"amount",
"types"
],
"type" : "object",
"properties" : {
"amount" : {
"type" : "integer",
"description" : "The amount to authorize in cents",
"format" : "int64",
"example" : 634
},
"types" : {
"minItems" : 1,
"type" : "array",
"description" : "Types supported by this category",
"example" : [
"FOOD"
],
"items" : {
"type" : "string",
"description" : "Types supported by this category",
"example" : "[\"FOOD\"]",
"enum" : [
"ECO",
"FOOD"
]
}
}
}
},
"WalletHybridPaymentRequest" : {
"required" : [
"amountDetails",
"callbackUrl",
"claimedUserIds",
"dpaId",
"merchantReference"
],
"type" : "object",
"properties" : {
"callbackUrl" : {
"minLength" : 1,
"type" : "string",
"description" : "The URL to receive the callback after the asynchronous operation is completed or has timed out.",
"example" : "https://my-api.com"
},
"claimedUserIds" : {
"uniqueItems" : true,
"type" : "array",
"description" : "Claimed User IDs. Typically an 'SDKID' (or ideally a 'DYNAMIC_SDKID') or some sort of additionalId/loyalty id ('LOYALTY').",
"items" : {
"$ref" : "#/components/schemas/ClaimedUserIdentifier"
}
},
"dpaId" : {
"type" : "string",
"description" : "The Mobile Payment Application ID",
"format" : "uuid",
"example" : "2bf169ba-9dd9-4b06-88c0-122b8843954f"
},
"merchantReference" : {
"minLength" : 1,
"type" : "string",
"description" : "The merchant reference is used to link the customers specific order to the PSP transaction",
"example" : "2e6d1236-4b3a-435d-a86c-6a15449a73df"
},
"proprietaryData" : {
"$ref" : "#/components/schemas/ProprietaryData"
},
"amountDetails" : {
"$ref" : "#/components/schemas/AmountDetailsWallet"
},
"categories" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/CategoryWallet"
}
},
"fullPayment" : {
"type" : "boolean",
"description" : "If set to true, the full amount must be covered. If set to false, a remaining amount is accepted by the merchant. Default true",
"example" : true
}
}
},
"PaymentMethod" : {
"type" : "object",
"properties" : {
"paymentMethod" : {
"type" : "string",
"enum" : [
"WALLET"
]
}
},
"description" : "List of payment methods to enable for the session",
"discriminator" : {
"propertyName" : "paymentMethod"
}
},
"WalletPayment" : {
"required" : [
"claimedUserIds",
"dpaId",
"wspId"
],
"type" : "object",
"allOf" : [
{
"$ref" : "#/components/schemas/PaymentMethod"
},
{
"type" : "object",
"properties" : {
"wspId" : {
"type" : "string",
"description" : "The Wallet Service Provider ID"
},
"claimedUserIds" : {
"type" : "array",
"description" : "The claimed user",
"items" : {
"$ref" : "#/components/schemas/ClaimedUserIdentifier"
}
},
"dpaId" : {
"type" : "string",
"description" : "The Mobile Payment Application ID"
},
"paymentInstrumentTypeWhiteList" : {
"type" : "array",
"description" : "The desired payment instrument types to use",
"items" : {
"type" : "string",
"description" : "The desired payment instrument types to use"
}
}
}
}
]
},
"WalletStatusResponse" : {
"type" : "object",
"properties" : {
"responseInfo" : {
"$ref" : "#/components/schemas/ResponseInfo"
},
"pspReference" : {
"type" : "string",
"description" : "The PSP reference to the payment"
},
"merchantReference" : {
"type" : "string",
"description" : "The merchant reference to the payment"
},
"status" : {
"type" : "string",
"description" : "Status of the wallet transaction"
},
"transactionDetails" : {
"type" : "array",
"description" : "List of status per operation",
"items" : {
"$ref" : "#/components/schemas/WalletTransactionDetails"
}
}
}
},
"WalletTransactionDetails" : {
"required" : [
"responseCode"
],
"type" : "object",
"properties" : {
"transactionId" : {
"type" : "string",
"description" : "PSP transaction ID"
},
"responseCode" : {
"minLength" : 1,
"type" : "string",
"description" : "Transaction status code"
},
"externalResponseCode" : {
"type" : "string",
"description" : "3rd party response code"
},
"amountDetails" : {
"$ref" : "#/components/schemas/AmountDetailsWallet"
},
"scheme" : {
"type" : "string",
"description" : "Payment scheme"
},
"brand" : {
"type" : "string",
"description" : "Payment brand"
},
"category" : {
"type" : "string",
"description" : "Category"
}
},
"description" : "List of status per operation"
}
}
}
}Merchant Callback API doc (swagger)
This API docs defines how the merchant/ECR should create their API to accept callback from the Aera PSP.
{
"openapi" : "3.0.1",
"info" : {
"title" : "Unified Commerce Services",
"description" : "Aera Payment & Identification Unified Commerce Platform",
"version" : "v1.0.0"
},
"externalDocs" : {
"description" : "Aera Payment & Identification Unified Commerce Platform Documentation",
"url" : "https://api-docs.aerahost.com/"
},
"servers" : [
{
"url" : "https://psp.aerahost.com/uc",
"description" : "Generated server url"
}
],
"tags" : [
{
"name" : "ecomHealth",
"description" : "API for eCom Services Health"
}
],
"paths" : {
"/v1/wlw/callback/merchant" : {
"post" : {
"tags" : [
"ecom"
],
"summary" : "The request to expect at the merchant after a completed Wallet payment",
"operationId" : "walletMerchantCallback",
"parameters" : [
{
"name" : "Accept",
"in" : "header",
"description" : "The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.",
"required" : true,
"schema" : {
"type" : "string"
}
},
{
"name" : "Content-Type",
"in" : "header",
"description" : "The content type of the body.",
"required" : true,
"schema" : {
"type" : "string"
}
}
],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/MerchantWalletCallbackRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"description" : "OK",
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/MerchantWalletCallbackResponse"
}
}
}
}
}
}
}
},
"components" : {
"schemas" : {
"ResponseInfo" : {
"required" : [
"responseCode",
"timeStamp"
],
"type" : "object",
"properties" : {
"message" : {
"type" : "string",
"description" : "Specific response message",
"example" : "Example message (often 'null' if responseCode=0)"
},
"responseCode" : {
"minLength" : 1,
"type" : "string",
"description" : "The response code from the system. Mandatory.",
"example" : "0"
},
"externalResponseCode" : {
"type" : "string",
"description" : "Additional response code from external systems.",
"example" : "0"
},
"cid" : {
"type" : "string",
"description" : "A Correlation ID (CID), which can eg. can be used in support cases.",
"example" : "Root=1-5759e988-bd862e3fe1be46a994272793"
},
"cidType" : {
"type" : "string",
"description" : "The type of Correlation ID (CID).",
"example" : "x-amzn-trace-id"
},
"timeStamp" : {
"type" : "string",
"description" : "Timestamp. Mandatory",
"example" : "2021-12-21T10:23:19.279Z"
}
},
"description" : "Info object that can provide specific messages"
},
"AmountDetailsWallet" : {
"required" : [
"amount",
"currency"
],
"type" : "object",
"properties" : {
"amount" : {
"type" : "integer",
"description" : "The amount to authorize in cents, including cashBackAmount",
"format" : "int64",
"example" : 1587
},
"cashBackAmount" : {
"type" : "integer",
"description" : "The amount used in cashBack in cents. Should be 'null' if no cashback amount.",
"format" : "int64"
},
"currency" : {
"type" : "string",
"description" : "The currency code (ISO 4217 alpha-3)",
"example" : "EUR"
}
},
"description" : "Payed amount in minor units"
},
"MerchantWalletCallbackRequest" : {
"required" : [
"merchantReference",
"pspReference",
"responseCode"
],
"type" : "object",
"properties" : {
"responseCode" : {
"type" : "string",
"description" : "ResponseCode"
},
"externalResponseCode" : {
"type" : "string",
"description" : "External ResponseCode"
},
"pspReference" : {
"type" : "string",
"description" : "PSP reference"
},
"merchantReference" : {
"type" : "string",
"description" : "Merchant reference"
},
"amountDetails" : {
"$ref" : "#/components/schemas/AmountDetailsWallet"
},
"transactionDetails" : {
"type" : "array",
"description" : "Details about a transaction, may contain multiple detail objects if hybrid transaction",
"items" : {
"$ref" : "#/components/schemas/WalletTransactionDetails"
}
}
}
},
"WalletTransactionDetails" : {
"required" : [
"responseCode"
],
"type" : "object",
"properties" : {
"transactionId" : {
"minLength" : 1,
"type" : "string",
"description" : "PSP transaction ID"
},
"responseCode" : {
"minLength" : 1,
"type" : "string",
"description" : "Transaction status code"
},
"externalResponseCode" : {
"type" : "string",
"description" : "3rd party response code"
},
"amountDetails" : {
"$ref" : "#/components/schemas/AmountDetailsWallet"
},
"scheme" : {
"type" : "string",
"description" : "Payment scheme"
},
"brand" : {
"type" : "string",
"description" : "Payment brand"
},
"category" : {
"type" : "string",
"description" : "Category"
}
},
"description" : "Details about a transaction, may contain multiple detail objects if hybrid transaction"
},
"MerchantWalletCallbackResponse" : {
"type" : "object",
"properties" : {
"responseInfo" : {
"$ref" : "#/components/schemas/ResponseInfo"
}
}
}
}
}
}Updated 7 days ago