المدفوعات
الدفع نقدًا
القسائم، والمبلغ الواجب دفعه، والآجال، والحد الأدنى 100 MAD، وأين يدفع عملاؤك، وما تفعله عند انتهاء صلاحية رمز.
في هذه الصفحة
في الدفع نقدًا، يحصل عميلك على رمز دفع، في قسيمة، ويسدده نقدًا لدى وكيل دفع شريك قبل أجل محدد. تعرف النتيجة من webhook، كما في البطاقة. يتيح لك الدفع نقدًا البيع لعملاء لا يملكون بطاقة، أو يفضّلون عدم استخدامها على الإنترنت.
لتجربته في دقائق قليلة، اتبع البدء السريع للدفع نقدًا.
كيف تسير الدفعة النقدية
- requires_payment_method → requires_action: إصدار الرمز
- requires_action → succeeded: دفع لدى وكيل، ثم تأكيد
- requires_action → requires_payment_method: انتهاء صلاحية أو رفض
- requires_action → canceled: تلغيها أنت
- يختار عميلك الدفع نقدًا في الصفحة المستضافة، أو تؤكد أنت نية دفع (payment intent) بالدفع نقدًا.
يحصل على قسيمة، وتصبح نية الدفع
requires_action. - يذهب إلى وكيل دفع شريك، ويقدّم الرمز، ويدفع نقدًا، ويحتفظ بإيصاله.
- يرصد فحص الحالة الدفع: تصبح نية الدفع
succeededوتتلقىpayment_intent.succeeded. في الوضع المباشر يجري الفحص كل دقيقتين، فيصل الحدث عادة خلال دقائق من الدفع؛ وفي وضع الاختبار يجري فورًا بعد الدفع المحاكى.
إلى أن تتأكد الدفعة، تبقى نية الدفع requires_action، وربما لأيام.
القواعد
- لا تقل الدفعة النقدية عن 100.00 MAD (
10000سنتيم)، في وضع الاختبار كما في الوضع المباشر. يُرفض أي مبلغ أصغر بالرمزamount_too_small. - الاسم الكامل والمدينة لعميلك إلزاميان. تطلبهما الصفحة المستضافة؛ ومع API
ترسل
payer.nameوpayer.cityعند التأكيد. رقم الهاتف اختياري. - العملة هي
mad، والمبالغ أعداد صحيحة بالسنتيم، كما في كل مكان في API.
القسيمة
توجد القسيمة في next_action.display_voucher ضمن نية الدفع:
| الحقل | ما يحمله |
|---|---|
code | رمز الدفع الذي يقدّمه عميلك لدى الوكيل. اعرضه كما هو: لا تغيّر أحرفه أبدًا. |
amount_to_pay | ما يسلّمه عميلك: مبلغك مضافًا إليه رسم طابع صغير يدفعه عميلك (0.25 MAD في وضع الاختبار). اعرض هذا الرقم كما تحدده القسيمة؛ ولا تحسبه أبدًا. لا يُقتطع الرسم من amount الخاص بك. |
expires_at | الأجل، بثواني Unix: نحو ثلاثة أيام بعد إصدار الرمز. اعرضه بتوقيت المغرب. |
slip_url | وصل قابل للطباعة. |
hosted_voucher_url | صفحة القسيمة لدينا، ويمكنك إرسالها إلى عميلك. |
تعرض صفحة القسيمة لدينا الرمز مع زر نسخ، والمبلغ الواجب تسليمه، والأجل بتوقيت المغرب، ومكان الدفع وطريقته، وأزرارًا لطباعتها ومشاركتها عبر واتساب أو رسالة نصية، وزر دفعت: تحقّق الآن. وهي بألوانك (الإعدادات ← العلامة التجارية) وتعمل على أي هاتف.
أين يدفع عملاؤك
لدى وكيل دفع شريك: يقدّم عميلك الرمز، ويدفع المبلغ الواجب تسليمه نقدًا، قبل الأجل، ويحتفظ بإيصال الوكيل. توضح صفحة القسيمة أي الوكلاء يقبلون الرمز وكيف يجد وكيلًا قريبًا.
في وضع الاختبار لا يقبل أي وكيل الرمز: تحاكي الدفع بدل ذلك، في صفحة القسيمة أو في لوحة التحكم أو عبر أدوات الاختبار المساعدة. وتجد كل النتائج في سيناريوهات اختبار الدفع النقدي.
عندما لا تسير الأمور كما يجب
| ما يحدث | ما تتلقاه | ما تفعله |
|---|---|---|
| ينقضي الأجل دون دفع | payment_intent.payment_failed، مع last_payment_error.code بقيمة voucher_expired؛ والعودة إلى requires_payment_method | حرّر الطلبية أو المخزون، أو دع عميلك يحصل على رمز جديد: في الصفحة المستضافة ما دامت الجلسة مفتوحة، أو بتأكيد نية الدفع من جديد. |
| ترفض شبكة الدفع الرمز | payment_intent.payment_failed مع voucher_refused | الأمر نفسه: يمكن لعميلك الحصول على رمز جديد. |
| يُعلَّق الرمز لدى الشبكة | لا شيء إلى أن يُدفع أو لا يُدفع | انتظر. |
| يدفع عميلك مبلغًا آخر، أو يدفع بعد الأجل أو بعد إلغائك | review.opened؛ ولا يُضاف شيء إلى رصيدك | انتظر: ينظر في الأمر أحد أعضاء فريقنا. انظر عندما لا يتطابق شيء. |
إلغاء رمز لم تعد تريده
إذا أُلغيت الطلبية قبل أن يدفع عميلك، فألغِ نية الدفع عبر
POST /v1/payment_intents/{id}/cancel. لا يمكن سداد الرمز بعد ذلك؛ وتتلقى
payment_intent.canceled.
إذا دفعه عميلك مع ذلك، فلا يُضاف شيء إلى رصيدك: تحصل الدفعة على مراجعة، وينظر فيها أحد أعضاء فريقنا. أخبر عميلك عندما تلغي.
curl -X POST \
https://pay-api.adpromax.com/v1/payment_intents/pi_01k7e6t4v8x2z5b9c3d7f1g6hq/cancel \
-u "$APX_SECRET_KEY:"const id = 'pi_01k7e6t4v8x2z5b9c3d7f1g6hq'
const response = await fetch(`https://pay-api.adpromax.com/v1/payment_intents/${id}/cancel`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.APX_SECRET_KEY}` },
})
const intent = await response.json()
console.log(intent.status) // canceledinterface PaymentIntent {
id: string
object: 'payment_intent'
status: string
}
const id = 'pi_01k7e6t4v8x2z5b9c3d7f1g6hq'
const response = await fetch(`https://pay-api.adpromax.com/v1/payment_intents/${id}/cancel`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.APX_SECRET_KEY}` },
})
const intent = (await response.json()) as PaymentIntent
console.log(intent.status) // canceledimport os
import requests
intent_id = "pi_01k7e6t4v8x2z5b9c3d7f1g6hq"
response = requests.post(
f"https://pay-api.adpromax.com/v1/payment_intents/{intent_id}/cancel",
auth=(os.environ["APX_SECRET_KEY"], ""),
)
print(response.json()["status"]) # canceled<?php
$id = 'pi_01k7e6t4v8x2z5b9c3d7f1g6hq';
$ch = curl_init("https://pay-api.adpromax.com/v1/payment_intents/{$id}/cancel");
curl_setopt_array($ch, [
CURLOPT_USERPWD => getenv('APX_SECRET_KEY') . ':',
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
]);
$intent = json_decode(curl_exec($ch), true);
echo $intent['status'], PHP_EOL; // canceledrequire 'json'
require 'net/http'
id = 'pi_01k7e6t4v8x2z5b9c3d7f1g6hq'
uri = URI("https://pay-api.adpromax.com/v1/payment_intents/#{id}/cancel")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch('APX_SECRET_KEY'), '')
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
http.request(request)
end
puts JSON.parse(response.body)['status'] # canceledpackage main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type PaymentIntent struct {
ID string `json:"id"`
Status string `json:"status"`
}
func main() {
id := "pi_01k7e6t4v8x2z5b9c3d7f1g6hq"
req, err := http.NewRequest(http.MethodPost,
"https://pay-api.adpromax.com/v1/payment_intents/"+id+"/cancel", nil)
if err != nil {
log.Fatal(err)
}
req.SetBasicAuth(os.Getenv("APX_SECRET_KEY"), "")
res, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer res.Body.Close()
var intent PaymentIntent
if err := json.NewDecoder(res.Body).Decode(&intent); err != nil {
log.Fatal(err)
}
fmt.Println(intent.Status) // canceled
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Cancel {
public static void main(String[] args) throws Exception {
String id = "pi_01k7e6t4v8x2z5b9c3d7f1g6hq";
HttpRequest request = HttpRequest.newBuilder(
URI.create("https://pay-api.adpromax.com/v1/payment_intents/" + id + "/cancel"))
.header("Authorization", "Bearer " + System.getenv("APX_SECRET_KEY"))
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// The payment intent as JSON: its status is now "canceled".
System.out.println(response.body());
}
}using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
var json = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower };
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("APX_SECRET_KEY"));
var id = "pi_01k7e6t4v8x2z5b9c3d7f1g6hq";
using var response = await http.PostAsync(
$"https://pay-api.adpromax.com/v1/payment_intents/{id}/cancel", null);
var intent = await response.Content.ReadFromJsonAsync<PaymentIntent>(json);
Console.WriteLine(intent!.Status); // canceled
record PaymentIntent(string Id, string Status);// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }
// serde = { version = "1", features = ["derive"] }
use serde::Deserialize;
#[derive(Deserialize)]
struct PaymentIntent {
status: String,
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let id = "pi_01k7e6t4v8x2z5b9c3d7f1g6hq";
let intent: PaymentIntent = reqwest::blocking::Client::new()
.post(format!("https://pay-api.adpromax.com/v1/payment_intents/{id}/cancel"))
.bearer_auth(std::env::var("APX_SECRET_KEY")?)
.send()?
.json()?;
println!("{}", intent.status); // canceled
Ok(())
}الدفع نقدًا لا يُسترد
لا يمكن استرداد دفعة نقدية ناجحة عبر AdProMaxPay، لا نقدًا ولا إلى بطاقة: انظر المبالغ المستردة لتعرف السبب، وما تفعله بدل ذلك.
من لوحة التحكم
يمكنك أيضًا استقبال دفعة نقدية بلا كود:
- إنشاء ← قسيمة دفع نقدي: مبلغ ابتداءً من 100.00 MAD، ووصف، وعميل إن أردت، واسم عميلك ومدينته، ورقم هاتف إن توفّر. ثم تتيح لك صفحة الدفعة مشاركة القسيمة عبر واتساب أو رسالة نصية أو رابط.
- روابط الدفع يمكن أن تعرض الدفع نقدًا إلى جانب البطاقة: يختار كل من يفتح الرابط.
صفحتك الخاصة
يمكنك عرض الرمز في صفحتك بدل صفحتنا: أنشئ نية دفع، وأكّدها
بالدفع نقدًا، ثم اعرض next_action.display_voucher. انظر
اعرض الرمز في صفحتك الخاصة.
ممارسات جيدة
- احجز الطلبية أو المخزون حتى الأجل، ثم حرّره عند
voucher_expired. - اعرض
amount_to_payوالأجل تمامًا كما تحددهما القسيمة، مع المنطقة الزمنية. - لا تعد بتأكيد فوري: أخبر عميلك أن الطلبية تتأكد عندما تتأكد دفعته.
- ذكّر عميلك قبل الأجل إن استطعت: معظم الرموز غير المدفوعة تنتهي صلاحيتها ببساطة.