{
  "openapi": "3.0.3",
  "info": {
    "title": "Statira Wallet-to-Wallet API",
    "version": "1.1.0",
    "description": "Free, same-currency wallet transfers between active approved Statira merchants, available through the dashboard and merchant APIs. No wallet-transfer webhooks or automatic reversals."
  },
  "servers": [
    {
      "url": "https://api.dev.paywithstatira.com",
      "description": "TEST keys"
    },
    {
      "url": "https://api.paywithstatira.com",
      "description": "LIVE keys"
    }
  ],
  "security": [
    {
      "PublicKey": [],
      "SecretKey": []
    }
  ],
  "paths": {
    "/api/v1/gateway/wallet": {
      "get": {
        "operationId": "getWallet",
        "summary": "Get and save your wallet ID",
        "description": "Requires wallet.view. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/gateway/wallet/transfers/recipient/{walletId}": {
      "get": {
        "operationId": "lookupWalletTransferRecipient",
        "summary": "Confirm recipient business name and currency",
        "description": "Requires wallet.payout. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "path",
            "name": "walletId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipientResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/gateway/wallet/transfers": {
      "post": {
        "operationId": "createWalletTransfer",
        "summary": "Send a free wallet-to-wallet transfer",
        "description": "Requires wallet.payout. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": "Nonblank. Persist before sending. Retry the identical request with the same key; scoped to sender wallet."
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Key already used with different transfer details or another data conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTransfer"
              },
              "example": {
                "recipientWalletId": "33333333-3333-4333-8333-333333333333",
                "amountMinor": 50000,
                "narration": "Invoice 123"
              }
            }
          }
        }
      }
    },
    "/api/v1/gateway/wallet/transfers/{reference}": {
      "get": {
        "operationId": "getWalletTransfer",
        "summary": "Verify a transfer involving your wallet",
        "description": "Requires wallet.view. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "path",
            "name": "reference",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Transfer not found or merchant is not a participant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ecommerce/wallet": {
      "get": {
        "operationId": "ecommerceGetWallet",
        "summary": "Get and save your wallet ID",
        "description": "Requires wallet.view. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "EcommerceKey": []
          }
        ]
      }
    },
    "/api/v1/ecommerce/wallet/transfers/recipient/{walletId}": {
      "get": {
        "operationId": "ecommerceLookupWalletTransferRecipient",
        "summary": "Confirm recipient business name and currency",
        "description": "Requires wallet.payout. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "path",
            "name": "walletId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipientResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "EcommerceKey": []
          }
        ]
      }
    },
    "/api/v1/ecommerce/wallet/transfers": {
      "post": {
        "operationId": "ecommerceCreateWalletTransfer",
        "summary": "Send a free wallet-to-wallet transfer",
        "description": "Requires wallet.payout. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "description": "Nonblank. Persist before sending. Retry the identical request with the same key; scoped to sender wallet."
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Key already used with different transfer details or another data conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTransfer"
              },
              "example": {
                "recipientWalletId": "33333333-3333-4333-8333-333333333333",
                "amountMinor": 50000,
                "narration": "Invoice 123"
              }
            }
          }
        },
        "security": [
          {
            "EcommerceKey": []
          }
        ]
      }
    },
    "/api/v1/ecommerce/wallet/transfers/{reference}": {
      "get": {
        "operationId": "ecommerceGetWalletTransfer",
        "summary": "Verify a transfer involving your wallet",
        "description": "Requires wallet.view. Active API keys must match the environment and whitelist the calling server IP.",
        "parameters": [
          {
            "in": "path",
            "name": "reference",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (also used for creation and replay).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or business rule rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, inactive or wrong-environment API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission or IP whitelist denied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error or unconfirmed outcome. For transfers retry the same key and body; intermediary errors may not be JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Transfer not found or merchant is not a participant.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "EcommerceKey": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PublicKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Public-Key"
      },
      "SecretKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Secret-Key"
      },
      "EcommerceKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Ecommerce-Key"
      }
    },
    "schemas": {
      "Wallet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "walletId": {
            "type": "string",
            "format": "uuid",
            "description": "Same value as id. Persist with merchant and environment."
          },
          "merchantId": {
            "type": "string",
            "format": "uuid"
          },
          "currencyCode": {
            "type": "string"
          },
          "availableBalanceMinor": {
            "type": "integer",
            "format": "int64"
          },
          "pendingBalanceMinor": {
            "type": "integer",
            "format": "int64"
          },
          "totalCreditedMinor": {
            "type": "integer",
            "format": "int64"
          },
          "totalDebitedMinor": {
            "type": "integer",
            "format": "int64"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "walletId",
          "merchantId",
          "currencyCode",
          "availableBalanceMinor",
          "pendingBalanceMinor",
          "totalCreditedMinor",
          "totalDebitedMinor",
          "updatedAt"
        ]
      },
      "Recipient": {
        "type": "object",
        "properties": {
          "walletId": {
            "type": "string",
            "format": "uuid"
          },
          "businessName": {
            "type": "string"
          },
          "currencyCode": {
            "type": "string"
          }
        },
        "required": [
          "walletId",
          "businessName",
          "currencyCode"
        ]
      },
      "Transfer": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string"
          },
          "senderWalletId": {
            "type": "string",
            "format": "uuid"
          },
          "recipientWalletId": {
            "type": "string",
            "format": "uuid"
          },
          "amountMinor": {
            "type": "integer",
            "format": "int64",
            "minimum": 1
          },
          "currencyCode": {
            "type": "string"
          },
          "narration": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "SUCCESS"
            ]
          }
        },
        "required": [
          "reference",
          "senderWalletId",
          "recipientWalletId",
          "amountMinor",
          "currencyCode",
          "narration",
          "status"
        ]
      },
      "CreateTransfer": {
        "type": "object",
        "properties": {
          "recipientWalletId": {
            "type": "string",
            "format": "uuid"
          },
          "amountMinor": {
            "type": "integer",
            "format": "int64",
            "minimum": 1,
            "maximum": 9223372036854775807,
            "description": "NGN kobo. No fee. Use safe integers in JavaScript."
          },
          "narration": {
            "type": "string",
            "maxLength": 140,
            "nullable": true
          }
        },
        "required": [
          "recipientWalletId",
          "amountMinor"
        ]
      },
      "WalletResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/Wallet"
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          },
          "correlationId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "success",
          "message",
          "data",
          "meta",
          "correlationId"
        ]
      },
      "RecipientResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/Recipient"
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          },
          "correlationId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "success",
          "message",
          "data",
          "meta",
          "correlationId"
        ]
      },
      "TransferResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/Transfer"
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          },
          "correlationId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "success",
          "message",
          "data",
          "meta",
          "correlationId"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "nullable": true,
            "description": "null on error"
          },
          "meta": {
            "type": "object",
            "additionalProperties": true
          },
          "correlationId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "success",
          "message",
          "data",
          "meta",
          "correlationId"
        ]
      }
    }
  }
}