Can I use $transaction->setReferenceId() with Paypal PHP REST API?

Question

I'm trying to include a identifier in the transaction so I know which transaction is when it returns from Paypal. I've tried to use the reference_id as it's like the better option (because is a temporal identifier that I assign to the transaction).

The problem is that when I set it to the transaction, Paypal refuse to accept the json, it returns:

{
   "name":"MALFORMED_REQUEST",
   "message":"Incoming JSON request does not map to API request",
   "information_link":"https://developer.paypal.com/webapps/developer/docs/api/#MALFORMED_REQUEST",
   "debug_id":"6835f984b6735"
}

More or less I use the example code:

// Create new payer and method
$payer = new Payer();
$payer->setPaymentMethod("paypal");

// Set redirect urls
$redirectUrls = new RedirectUrls();
$redirectUrls->setReturnUrl($urlRetorno)
    ->setCancelUrl($urlCancelar);

// Set payment amount
$amount = new Amount();
$amount->setCurrency($moneda)
    ->setTotal($total);

// Set transaction object
$transaction = new Transaction();
$transaction->setAmount($amount)
    ->setDescription($descripcion);

// If I comment this line it runs ok.
$transaction->setReferenceId($referenceId);

// Create the full payment object
$payment = new Payment();
$payment->setIntent('sale')
    ->setPayer($payer)
    ->setRedirectUrls($redirectUrls)
    ->setTransactions(array($transaction));

echo $payment->toJSON();

// Create payment with valid API context
try {

    $payment->create($apiContext);

    // Get PayPal redirect URL and redirect user
    $approvalUrl = $payment->getApprovalLink();

    // Finalmente le redirigimos a PayPal para que apruebe el pago
    //redirige($approvalUrl, 'Intentando redirigir a PayPal.');

} catch (PayPal\Exception\PayPalConnectionException $ex) {
    echo $ex->getCode();
    echo $ex->getData();
    die($ex);
} catch (Exception $ex) {
    die($ex);
}

And this is the result (calling toJSON()):

{
   "intent":"sale",
   "payer":{
      "payment_method":"paypal"
   },
   "redirect_urls":{
      "return_url":"https://example.com/return.php",
      "cancel_url":"https://example.com/cancel.php"
   },
   "transactions":[
      {
         "amount":{
            "currency":"MXN",
            "total":"1515"
         },
         "description":"Suscripci\u00f3n c\u00f3digo PP-19119",
         "reference_id":"304171757041"
      }
   ]
}

I have found the reference_id in the API documentation so I supposed I could use it.

Answer 1

After posting on the GitHub repositories about it here is the conclusion.

reference_id is a read only value and you should use invoice_number to track it.

You can read about it in https://github.com/paypal/PayPal-PHP-SDK/issues/828 and currently tracked in https://github.com/paypal/PayPal-REST-API-issues/issues/69.