{ "openapi": "3.1.0", "info": { "title": "SofizPay REST API", "description": "The official REST API for SofizPay — Algeria's most comprehensive payment gateway. Integrate EDAHABIA of Algerie Poste and CIB of SATIM for phone recharge, internet packages, gaming credits, bill payments, and e-commerce. Open-source SDKs available at github.com/SofizPay. 0% API transaction fees.", "version": "1.0.0", "contact": { "name": "SofizPay Developer Support", "email": "contact@sofizpay.com", "url": "https://docs.sofizpay.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "x-logo": { "url": "https://docs.sofizpay.com/og-image.jpg", "altText": "SofizPay Logo" } }, "externalDocs": { "description": "Full SofizPay Developer Documentation", "url": "https://docs.sofizpay.com/en/api/v1/introduction" }, "servers": [ { "url": "https://api.sofizpay.com/v1", "description": "SofizPay Production API v1" } ], "tags": [ { "name": "Phone Recharge", "description": "Recharge Mobilis, Djezzy, and Ooredoo mobile phone credit (Flexy) in Algeria." }, { "name": "Internet Recharge", "description": "Recharge Idoom ADSL, Idoom 4G LTE, and Djaweb internet packages." }, { "name": "Game Credits", "description": "Purchase gaming credits: PUBG UC, Free Fire diamonds, Mobile Legends, and more." }, { "name": "CIB Payment (SATIM)", "description": "Initiate and verify CIB bank card payments via SATIM network." }, { "name": "Bill Payments", "description": "Pay Algerian utility bills: Sonelgaz, ADE water, Algérie Télécom." }, { "name": "Operations", "description": "Retrieve transaction history and operation details." }, { "name": "Products", "description": "Get the catalog of available products and services." }, { "name": "Tools", "description": "Payment links and QR code generators." }, { "name": "Merchant", "description": "Merchant invoices and product catalog management." } ], "paths": { "/recharge/phone": { "post": { "tags": [ "Phone Recharge" ], "summary": "Recharge phone credit (Flexy)", "description": "Recharge Algerian mobile phone credit for Mobilis, Djezzy, or Ooredoo via SofizPay API. Supports all Flexy denominations.", "operationId": "rechargePhone", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRechargeRequest" } } } }, "responses": { "200": { "description": "Recharge successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — invalid API key" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recharge/internet": { "post": { "tags": [ "Internet Recharge" ], "summary": "Recharge internet package", "description": "Recharge Algerian internet packages: Idoom ADSL, Idoom 4G LTE, Djaweb.", "operationId": "rechargeInternet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternetRechargeRequest" } } } }, "responses": { "200": { "description": "Recharge successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/recharge/game": { "post": { "tags": [ "Game Credits" ], "summary": "Purchase gaming credits", "description": "Purchase gaming credits for PUBG UC, Free Fire diamonds, Mobile Legends diamonds, and other popular games in Algeria.", "operationId": "rechargeGame", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GameRechargeRequest" } } } }, "responses": { "200": { "description": "Game credits purchased", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cib/transaction": { "post": { "tags": [ "CIB Payment (SATIM)" ], "summary": "Make a CIB (SATIM) payment transaction", "description": "Initiate a CIB bank card payment transaction via the SATIM network. Supports 3D Secure authentication. Returns a redirect URL for the payment page.", "operationId": "makeCibTransaction", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CibTransactionRequest" } } } }, "responses": { "200": { "description": "Transaction initiated — redirect URL returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CibTransactionResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/cib/transaction/check": { "post": { "tags": [ "CIB Payment (SATIM)" ], "summary": "Check CIB transaction status", "description": "Verify the status of a CIB (SATIM) payment transaction by order number. Returns real-time payment confirmation.", "operationId": "cibTransactionCheck", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CibCheckRequest" } } } }, "responses": { "200": { "description": "Transaction status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CibCheckResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/bills/pay": { "post": { "tags": [ "Bill Payments" ], "summary": "Pay an Algerian utility bill", "description": "Pay Algerian utility bills including Sonelgaz electricity, ADE water bills, and Algérie Télécom phone bills via SofizPay API.", "operationId": "payBill", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillPaymentRequest" } } } }, "responses": { "200": { "description": "Bill payment successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/operations/{operationId}": { "get": { "tags": [ "Operations" ], "summary": "Get operation details", "description": "Retrieve full details of a specific transaction by its operation ID.", "operationId": "getOperationDetails", "parameters": [ { "name": "operationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDetails" } } } }, "404": { "description": "Operation not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/operations": { "get": { "tags": [ "Operations" ], "summary": "Get operation history", "description": "Retrieve paginated transaction history for your SofizPay account. Filter by date range, type, and status.", "operationId": "getOperationHistory", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "phone", "internet", "game", "cib", "bill" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated list of operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationHistory" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/products": { "get": { "tags": [ "Products" ], "summary": "Get available products catalog", "description": "Retrieve the complete catalog of available products and services: phone operators, internet packages, game titles, bill payment options.", "operationId": "getProducts", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "phone", "internet", "game", "bill" ] } } ], "responses": { "200": { "description": "Products catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductsCatalog" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/merchant/invoices": { "get": { "tags": [ "Merchant" ], "summary": "List merchant invoices", "description": "Retrieve all merchant invoices for your SofizPay account.", "operationId": "listMerchantInvoices", "responses": { "200": { "description": "List of invoices" } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "Merchant" ], "summary": "Create a merchant invoice", "description": "Create a new merchant invoice for your SofizPay store.", "operationId": "createMerchantInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } } }, "responses": { "201": { "description": "Invoice created" } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your SofizPay API key from the merchant dashboard." } }, "schemas": { "PhoneRechargeRequest": { "type": "object", "required": [ "phone_number", "operator", "amount" ], "properties": { "phone_number": { "type": "string", "example": "0661234567", "description": "Algerian phone number (10 digits)" }, "operator": { "type": "string", "enum": [ "mobilis", "djezzy", "ooredoo" ], "description": "Mobile operator" }, "amount": { "type": "integer", "example": 100, "description": "Recharge amount in DZD" } } }, "InternetRechargeRequest": { "type": "object", "required": [ "subscription_number", "provider", "package_id" ], "properties": { "subscription_number": { "type": "string", "description": "Idoom or ISP subscription number" }, "provider": { "type": "string", "enum": [ "idoom_adsl", "idoom_4g", "djaweb" ], "description": "Internet provider" }, "package_id": { "type": "string", "description": "Internet package ID from /products" } } }, "GameRechargeRequest": { "type": "object", "required": [ "game_id", "product_id", "player_id" ], "properties": { "game_id": { "type": "string", "example": "pubg", "description": "Game identifier (pubg, freefire, ml, etc.)" }, "product_id": { "type": "string", "description": "Game product ID from /products" }, "player_id": { "type": "string", "description": "In-game player/account ID" } } }, "CibTransactionRequest": { "type": "object", "required": [ "amount", "currency", "order_id", "return_url" ], "properties": { "amount": { "type": "number", "example": 5000, "description": "Transaction amount" }, "currency": { "type": "string", "enum": [ "DZD" ], "default": "DZD" }, "order_id": { "type": "string", "description": "Your unique order reference" }, "return_url": { "type": "string", "format": "uri", "description": "URL to redirect after payment" }, "description": { "type": "string", "description": "Payment description shown to customer" } } }, "CibTransactionResponse": { "type": "object", "properties": { "order_id": { "type": "string" }, "payment_url": { "type": "string", "format": "uri", "description": "Redirect the customer to this URL" }, "status": { "type": "string", "enum": [ "pending" ] } } }, "CibCheckRequest": { "type": "object", "required": [ "order_id" ], "properties": { "order_id": { "type": "string", "description": "The order ID from makeCibTransaction" } } }, "CibCheckResponse": { "type": "object", "properties": { "order_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "paid", "failed", "cancelled" ] }, "amount": { "type": "number" }, "paid_at": { "type": "string", "format": "date-time" } } }, "BillPaymentRequest": { "type": "object", "required": [ "bill_type", "reference", "amount" ], "properties": { "bill_type": { "type": "string", "enum": [ "sonelgaz", "ade", "algerie_telecom" ], "description": "Type of Algerian utility bill" }, "reference": { "type": "string", "description": "Bill reference/contract number" }, "amount": { "type": "number", "description": "Amount to pay in DZD" } } }, "OperationResponse": { "type": "object", "properties": { "operation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "pending", "failed" ] }, "amount": { "type": "number" }, "type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OperationDetails": { "type": "object", "properties": { "operation_id": { "type": "string" }, "type": { "type": "string", "enum": [ "phone", "internet", "game", "cib", "bill" ] }, "status": { "type": "string", "enum": [ "success", "pending", "failed", "cancelled" ] }, "amount": { "type": "number" }, "fee": { "type": "number", "description": "Transaction fee (0 for API transactions)" }, "metadata": { "type": "object", "description": "Operation-specific data" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OperationHistory": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OperationDetails" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "ProductsCatalog": { "type": "object", "properties": { "phone": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "internet": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "game": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "bill": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "Product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "name_ar": { "type": "string", "description": "Arabic name" }, "price": { "type": "number" }, "currency": { "type": "string", "default": "DZD" } } }, "CreateInvoiceRequest": { "type": "object", "required": [ "title", "amount" ], "properties": { "title": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string", "default": "DZD" }, "description": { "type": "string" } } }, "Error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "message_ar": { "type": "string", "description": "Error message in Arabic" } } } } }, "x-algerian-payment": { "edahabia": true, "cib_satim": true, "country": "DZ", "currency": "DZD", "languages": [ "ar", "fr", "en" ] } }