API Apex pour les développeurs

Tout ce que font les écrans de REDA Pay est aussi accessible à Apex dans votre organisation, au moyen d’une seule classe globale. Utilisez-la lorsqu’un flux ne suffit pas : une page de paiement personnalisée, un script de migration qui enregistre chez Payload des clients existants, une intégration qui doit traiter un ordre et lire le résultat de manière synchrone.

Avant de commencer

Vous êtes développeur Salesforce avec l’autorisation Author Apex, et vous travaillez dans une sandbox avec l’environnement de test de Payload.
L’utilisateur qui exécute le code a besoin de l’ensemble d’autorisations REDA Pay correspondant à l’opération (Admin User pour les opérations de configuration ; Transaction Manager pour l’annulation et le remboursement) et, pour les décaissements, de REDA Pay - Enable Disbursements.
Chaque méthode effectue un appel externe (callout) vers Payload. Appelez-les depuis un contexte qui autorise les appels externes (une méthode future, queueable ou batch, ou un contrôleur sans travail en attente non validé).

La classe

Toutes les méthodes sont statiques sur rpay.PayAPIGlobal et renvoient un rpay.TransactionResult.

Méthode	Ce qu’elle fait
`createPayCustomer(Id payCustomerId)`	Enregistre le Pay Customer chez Payload et stocke l’identifiant client
`updatePayCustomer(Id payCustomerId)`	Envoie à Payload le nom, l’e-mail et le téléphone du client
`createPayMethod(Id payMethodId, rpay.PayMethodWrapper details)`	Enregistre une carte ou un compte bancaire pour un enregistrement Pay Method existant et stocke le jeton et les informations descriptives
`deletePayMethod(Id payMethodId)`	Supprime le moyen chez Payload ; l’enregistrement est conservé, marqué comme supprimé
`processPayOrder(Id payOrderId, rpay.PayMethodWrapper details)`	Traite un ordre Immediate. Passez `details` pour enregistrer au passage une nouvelle carte ou un nouveau compte, ou `null` pour utiliser le Pay Method enregistré de l’ordre
`voidTransaction(Id transactionId, Date voidedDate, String voidingReason)`	Annule une transaction traitée et pas encore financée
`refundTransaction(Id transactionId, Decimal refundAmount, String description, Date refundDate)`	Rembourse un paiement traité, en totalité ou en partie, en créant une transaction de remboursement
`syncTransaction(Id transactionId)`	Relit une transaction chez Payload
`syncPayOrderTransactions(Id payOrderId)`	Lit toutes les transactions que Payload détient pour l’ordre ; met à jour et crée ce qu’il faut

Deux anciennes signatures, voidTransaction(Id) et refundTransaction(Id, Decimal, String), compilent toujours mais lèvent l’exception « This method is deprecated. Please follow the documentation for updated method details. » (méthode obsolète). Utilisez les signatures complètes.

`rpay.PayMethodWrapper`

Les informations de carte ou de compte bancaire pour createPayMethod et processPayOrder :

Champ	Carte	Compte bancaire
`methodType`	`card`	`bank_account`
`cardNumber`, `cardHolderName`, `cardCVV`, `cardExpiry` (MM/AA), `cardType`	✓
`accountName`, `accountNumber`, `routingNumber` (9 chiffres), `accountType`, `accountClass`, `accountCurrency`		✓
`postalCode`	✓	✓

Ces valeurs transitent par votre Apex jusqu’à Payload et ne sont jamais stockées ; consultez Sécurité et données de carte. Ne les journalisez pas, ne les stockez pas dans des champs et ne les placez pas dans des instructions de débogage.

`rpay.TransactionResult`

Champ	Signification
`isSuccess`	Indique si l’opération a réussi
`error_message`	La raison, en cas d’échec
`payorder_name`, `payorder_sfid`	Le numéro et l’Id de l’ordre
`transaction_id`, `transaction_ref`, `transaction_sfid`, `transaction_obj`	L’identifiant et la référence de la transaction chez Payload, et l’enregistrement Pay Transaction
`customer_id`, `customer`	L’identifiant client chez Payload et l’enregistrement Pay Customer
`pay_method_id`, `pay_method_description`, `isDefaultMethod`, `card_name`, `card_last4`, `card_brand`, `card_type`, `card_exp_month`, `card_exp_year`	Le jeton et les informations descriptives du moyen enregistré

Quelques autres champs (identification_number, identification_type, external_url, le groupe three_d_secure_mode) existent pour un usage futur et ne sont pas renseignés dans cette version.

Exemple : traiter un ordre avec un moyen enregistré

// Le Pay Order existe, il est Immediate, non traité, et a déjà un Pay Method actif.
rpay.TransactionResult r = rpay.PayAPIGlobal.processPayOrder(payOrderId, null);
if (r.isSuccess) {
    System.debug('Processed ' + r.payorder_name + ' as ' + r.transaction_ref);
} else {
    System.debug('Failed: ' + r.error_message);   // une Pay Transaction en échec a été enregistrée sous l’ordre
}

Exemple : enregistrer le compte bancaire d’un fournisseur

rpay.PayMethodWrapper w = new rpay.PayMethodWrapper();
w.methodType      = 'bank_account';
w.accountName     = 'Harbor Maintenance LLC';
w.accountNumber   = accountNumberFromYourSecureInput;   // ne jamais l’écrire en dur ni le journaliser
w.routingNumber   = '021000021';
w.accountType     = 'checking';
w.accountClass    = 'business';
w.accountCurrency = 'USD';
w.postalCode      = '33602';

// payMethodId est un enregistrement Pay Method créé avec Pay Customer, Pay Profile,
// Pay Method Type = bank_account et Transfer Type = receive-only (décaissement).
rpay.TransactionResult r = rpay.PayAPIGlobal.createPayMethod(payMethodId, w);

Règles qui s’appliquent aussi aux appels de l’API

Les mêmes validations que dans les écrans : le profil et le compte doivent être actifs ; le client, le compte et le moyen doivent autoriser le type de transfert et le type de moyen ; l’utilisateur qui exécute le code doit être autorisé pour ce sens ; un ordre traité ne peut pas être traité à nouveau. Les violations reviennent dans error_message.
Les frais de service sont calculés à l’enregistrement de l’ordre, à partir des Fee Setups du compte ; renseignez Zero Convenience Fee ou Convenience Fee Override sur l’ordre avant le traitement si nécessaire.
Les méthodes appellent Payload un enregistrement à la fois. Bouclez dans votre code en surveillant les limites d’appels externes, ou confiez le travail en masse à un batch.
processPayOrder avec details enregistre le moyen avant le débit : une carte enregistrée de cette façon est conservée pour être réutilisée, sauf si vous décochez ensuite Keep Active.

La classe de planification

rpay.SchedulePayOrderJob est la tâche quotidienne des paiements récurrents. Elle est planifiable et a deux propriétés modifiables, processDate (par défaut, aujourd’hui) et batchSize (par défaut, 50) ; consultez Planifier la tâche quotidienne des paiements récurrents.

Erreurs à éviter

Erreur	Ce qui se passe	Correction
Appeler l’API après une opération DML dans la même transaction	Exception d’appel externe (callout)	Appelez-la depuis un contexte asynchrone, ou avant toute opération DML
Passer des données de carte provenant d’une source non fiable sans les valider	Payload les rejette ; pire, vous risquez de les journaliser	Validez, ne journalisez jamais
S’attendre à ce que `processPayOrder` crée l’ordre	La méthode traite un Pay Order existant	Insérez d’abord l’ordre
Utiliser les signatures obsolètes d’annulation et de remboursement	Une exception	Utilisez les signatures avec date
Exécuter le code avec un utilisateur qui n’a pas l’ensemble d’autorisations	Erreurs d’accès	Attribuez REDA Pay - Admin User à l’utilisateur d’intégration

Questions fréquentes

Pas propre à REDA Pay. Exposez les méthodes globales au moyen de votre propre classe Apex REST si un système externe en a besoin, et protégez-la en conséquence.

Créez les enregistrements par un chargement de données, puis appelez createPayCustomer et createPayMethod depuis un batch, un enregistrement par exécution, dans le respect des limites de débit de Payload.

Non. Elle s’exécute en tant qu’utilisateur actuel, avec les mêmes contrôles d’accès que les écrans.