dolibarr 25.0.0-alpha
paymentref.lib.php File Reference

Generation of the structured payment reference. More...

Go to the source code of this file.

Functions

 dolPayRefGetSchemeForCountry ($country_code)
 Return the payment reference scheme to use for a country.
 
 dolPayRefFormatForDisplay ($ref, $country_code='')
 Format a payment reference the way its country prints it.
 
 dolPayRefGetSetupWarning ($country_code, $mode='')
 Return the setup that is still missing before references can be generated.
 
 dolPayRefBuild ($payment_id, $statut, $country_code, $invoice_type=0)
 Build a structured payment reference from a payment id, for a country.
 
 dolPayRefGenerateForInvoice ($object, $user, $store=1)
 Generate and optionally store the payment reference of an invoice.
 
 dolPayRefGetThirdpartyBase ($thirdparty)
 Return the value a third party builds its payment reference from.
 
 dolPayRefCollectParts ($object)
 Collect the ordered parts used to build a per invoice reference.
 
 dolPayRefGetLinkedContractRef ($object)
 Return the reference of the first contract linked to an invoice.
 

Detailed Description

Generation of the structured payment reference.

Definition in file paymentref.lib.php.

Function Documentation

◆ dolPayRefBuild()

dolPayRefBuild ( $payment_id,
$statut,
$country_code,
$invoice_type = 0 )

Build a structured payment reference from a payment id, for a country.

This is the single place that maps a country to its national algorithm.

Parameters
string$payment_idValue to encode. Customer code, invoice number, or a combination, depending on mode.
int<0,3>$statut Invoice status. Returns '' when lower than 1.
string$country_codeCreditor country code
int$invoice_typeInvoice type, used by the belgian scheme
Returns
string Payment reference, or '' on error

Definition at line 154 of file paymentref.lib.php.

References dol_syslog(), dolBECalculateStructuredCommunication(), dolCreditorRefGenerate(), dolCreditorRefIsValid(), dolFICalculatePaymentReference(), dolFIIsValidReference(), dolGRCalculateCreditorReference(), dolGRIsAmountCheckedReference(), dolPayRefGetSchemeForCountry(), and dolPayRefStrip().

Referenced by dolPayRefGenerateForInvoice().

◆ dolPayRefCollectParts()

dolPayRefCollectParts ( $object)

Collect the ordered parts used to build a per invoice reference.

Parts are listed in INVOICE_PAYMENT_REF_PARTS as a comma separated list. Accepted values are 'customer_code', 'contract_ref' and 'invoice_ref'.

Parameters
CommonObject$objectInvoice, proposal or order
Returns
string[] Ordered non empty parts

Definition at line 350 of file paymentref.lib.php.

References $object, dolPayRefGetLinkedContractRef(), and getDolGlobalString().

Referenced by dolPayRefGenerateForInvoice().

◆ dolPayRefFormatForDisplay()

dolPayRefFormatForDisplay ( $ref,
$country_code = '' )

Format a payment reference the way its country prints it.

Presentation only. The stored value stays compact, because the QR code, the barcode and the SEPA file all need it unspaced.

  • greek references are printed unbroken, all 25 characters
  • a belgian structured communication already carries its own separators
  • everything else is grouped in fours, the ISO 11649 convention
Parameters
string$refStored payment reference
string$country_codeCreditor country code
Returns
string Reference as it should appear on a document

Definition at line 67 of file paymentref.lib.php.

References dolPayRefDetectScheme(), dolPayRefFormat(), dolPayRefGetSchemeForCountry(), and dolPayRefStrip().

Referenced by pdf_sponge\drawInfoTable().

◆ dolPayRefGenerateForInvoice()

dolPayRefGenerateForInvoice ( $object,
$user,
$store = 1 )

Generate and optionally store the payment reference of an invoice.

Called from Facture\validate() with $store = 1, and from the invoice card with $store = 0 to show a preview on a draft.

Three modes, set with INVOICE_PAYMENT_REF_MODE in Home - Setup - Invoices:

'company' One fixed reference for the whole company. Every invoice carries the same value, taken from MAIN_INFO_SOCIETE_PAYMENT_ID. 'thirdparty' One stable reference per customer, generated once from the customer code and kept in llx_societe.tp_payment_reference, then reused on every invoice of that customer. 'invoice' One reference per invoice, built from the parts listed in INVOICE_PAYMENT_REF_PARTS.

Parameters
CommonObject$objectInvoice, or a proposal or order used only to preview the reference the invoice will carry. Needs ->ref, ->status, ->type and ->thirdparty.
User$userUser doing the action, for setValueFrom
int<0,1>$store 1 to write to database, 0 for preview only
Returns
string Payment reference, or '' when disabled or on error

Definition at line 233 of file paymentref.lib.php.

References $mysoc, $object, dol_strlen(), dol_syslog(), dolCreditorRefGenerateFromParts(), dolPayRefBuild(), dolPayRefCollectParts(), dolPayRefGetSchemeForCountry(), dolPayRefGetThirdpartyBase(), and getDolGlobalString().

Referenced by Facture\validate().

◆ dolPayRefGetLinkedContractRef()

dolPayRefGetLinkedContractRef ( $object)

Return the reference of the first contract linked to an invoice.

Parameters
CommonObject$objectInvoice, proposal or order, needs ->id and ->db
Returns
string Contract reference, or ''

Definition at line 385 of file paymentref.lib.php.

References $object, and dol_syslog().

Referenced by dolPayRefCollectParts().

◆ dolPayRefGetSchemeForCountry()

dolPayRefGetSchemeForCountry ( $country_code)

Return the payment reference scheme to use for a country.

The scheme decides which country library builds the reference. It is not a user preference, it follows the national banking rules of the creditor.

Parameters
string$country_codeISO 3166-1 alpha-2 country code
Returns
string 'BE', 'FI', 'GR' or 'RF' for plain ISO 11649

Definition at line 34 of file paymentref.lib.php.

References dol_strtoupper().

Referenced by dolPayRefBuild(), dolPayRefFormatForDisplay(), dolPayRefGenerateForInvoice(), and dolPayRefGetSetupWarning().

◆ dolPayRefGetSetupWarning()

dolPayRefGetSetupWarning ( $country_code,
$mode = '' )

Return the setup that is still missing before references can be generated.

Some schemes need a value that cannot be chosen freely. The greek DIAS code is assigned by the bank, so without it nothing can be produced and the invoice would be validated with an empty reference.

Parameters
string$country_codeCreditor country code
string$modeMode to check. Empty checks the stored one, so a setup page can test a mode before saving it.
Returns
string Translation key of the warning, or '' when the setup is complete

Definition at line 98 of file paymentref.lib.php.

References dolCreditorRefIsValid(), dolGRIsAmountCheckedReference(), dolGRIsValidDiasCode(), dolPayRefGetSchemeForCountry(), and getDolGlobalString().

◆ dolPayRefGetThirdpartyBase()

dolPayRefGetThirdpartyBase ( $thirdparty)

Return the value a third party builds its payment reference from.

The field follows INVOICE_PAYMENT_REF_TP_BASE from the setup. A third party that needs a different reference has it written directly on its card instead. The internal id is the last resort so a reference can always be produced.

Parameters
Societe$thirdpartyThird party
Returns
string Value to encode, never empty

Definition at line 316 of file paymentref.lib.php.

References getDolGlobalString().

Referenced by dolPayRefGenerateForInvoice().