中东支付网关API接入指南

中东支付网关API接入指南

1. 中东支付市场概述

中东地区(包括海湾合作委员会GCC国家)的支付生态具有以下特点：

  • 信用卡普及率较高，但现金仍占重要地位
  • Mada卡(沙特)、Fawry(埃及)、Benefit Pay(巴林)等本地支付方式流行
  • 伊斯兰金融合规要求严格
  • VAT税率普遍为5%-15%

2. 主流支付网关提供商

a. PayTabs (总部：沙特)

specificities::

  • GCC地区领先的全渠道解决方案
  • 支持Mada、Apple Pay、Visa/Mastercard等
  • API文档完善，提供沙盒环境

b. Telr (总部：阿联酋)

specificities::

  • Shopify官方推荐的中东支付方案
  • One-page checkout解决方案

3. PayTabs API接入详细指南

a. 注册与认证流程

  1. 商户注册::

    • 访问PayTabs官网提交商业注册文件（需英文或阿拉伯文）
    • GCC国家需要提供CR(Commercial Registration)副本
    • VAT税号登记（如适用）

  2. 账户验证::

    • 企业银行账户验证（中东本地账户更易通过）
    • AML/KYC合规审查（通常需3-5个工作日）

b. API基础配置

# Python示例代码 - PayTabs初始化

import requests



PAYTABS_MERCHANT_EMAIL = "[email protected]"

PAYTABS_SECRET_KEY = "sk_live_xxxxxxxxxxxxxx"

PAYTABS_BASE_URL = "https://secure.paytabs.com/"



headers = {

    "Authorization": PAYTABS_SECRET_KEY,

    "Content-Type": "application/json"

}

c. 核心API端点

functionality HTTP方法 Endpoint
创建支付页面 POST /payment/request
交易查询 GET /payment/query/{transaction_id}
退款处理 POST /payment/refund

4. Telr集成关键步骤

a. SDK集成方式

// JavaScript前端集成示例(Telr嵌入式支付)

TelrGateway.init({

    key: 'MERCHANT_KEY',

    complete: function(response) {

        if (response.status === 'approved') { 

            // Payment success logic 

        }

    }

});

b. Webhook配置要求

必须实现以下通知URL：

  • https://yourdomain.com/telr/callback (HTTP POST)
  • Content-Type: application/x-www-form-urlencoded

安全建议::
1）验证authkey参数
2）IP白名单设置：54.77..

5. Mada卡特殊处理方案

沙特地区Mada卡支付需要额外参数：

{

    "payment_method": "mada",

    "customer_details": { 

        "id_number": "{沙特身份证号/Iqama号}",

        "bank_code": "{发卡行代码}"

     }

}

注意：Mada交易手续费通常比国际信用卡低0.5%-1%

FAQ常见问题解决方案

Q1: GCC地区常见的API调用失败原因？
A1:
✅ IP未加入白名单(联系网关技术支持添加)
✅ VAT计算错误(确保传参包含tax_amount字段)

Q2: Arab Bank等本地银行拒绝交易？
A2:
• Header中添加 "Accept-Language":"ar"
• Billing地址必须包含阿拉伯字符版本